Skip to content

Getting started: nineteen blanks become four, and step one stops being a compile - #24

Merged
FlagshipDev merged 1 commit into
mainfrom
publish/2026-08-10-4b7696e
Aug 10, 2026
Merged

Getting started: nineteen blanks become four, and step one stops being a compile#24
FlagshipDev merged 1 commit into
mainfrom
publish/2026-08-10-4b7696e

Conversation

@FlagshipDev

Copy link
Copy Markdown
Contributor

Five items about the same thing — what somebody sees before Hullwork works for them — and every one
of them found the product already knew the answer and was not saying it.

init says what you need, not what everybody needs

It wrote a 120-line environment file with nineteen empty variables and printed the same five
numbered steps to every reader. Those steps were the union: an instance that only ingests errors
needs four of the nineteen, one that attempts fixes needs seven, and nothing said which reader was
which.

It now asks five questions — enter answers all of them — writes what you gave it, and reports what
is still missing for the capabilities you asked for, each with what it buys. Four lines instead
of nineteen blanks. No question asks for a secret: they ask which things exist, never what they are,
and the report never prints a value.

The checks arrive before the containers, not after

Every check hullwork doctor makes now runs during init, before anything is built or started.
That was always possible and nobody had noticed: the checks need a database session, and an
in-memory one satisfies both that and the rule that a setup command must not create a database file
in whatever directory you are standing in.

And one check that did not exist anywhere: does the forge you named actually answer, and what may
your token do there.
doctor touches no network — it reported ok for a hostname that does not
resolve, because the question it asks is which forge is this configured for. So the first sign
that a token was wrong used to be projects add refusing it.

Three answers, kept apart: reached it and it is fine, reached it and it is wrong, and could not
reach it from here
— which is a fact about your machine as much as about the forge, is reported as
such, and never sets the exit code. A laptop behind a VPN does not fail your install.

init is safe to run again and again; the second run is the report on its own, which is what you
want after pasting a credential. It reaches the network only when a forge is configured, and its
help says so.

Step one is no longer a compile

Two compose files shipped, and the one written for real deployments was the one that needed a
checkout: it built from source and did not contain the string ghcr.io anywhere, while the file
that pulls the published image was labelled the evaluation stack. So the documented path was clone
the source, build 500 MB, and never find out a published image exists.

init now writes a compose file that pulls a pinned published image — the version of the image that
wrote it, which is provably one you just pulled. Building is still there, explicit, four commented
lines and the sentence saying when you want it: when you are changing Hullwork's own code, which is
what the build variable was always for. It is no longer among the things the report says a person
must supply.

The gateway that observes and seals model traffic used to run from a hardcoded image name, whose own
comment named the assumption that pulling breaks — the image this installation built. It now
follows the image the instance runs.

What is not claimed

Nobody outside this project has installed Hullwork, and this changes what the first hour looks like
rather than proving anything about it. The measurements here are of the commands, not of a stranger
using them. docs/status.md remains the honest scope.

Signed-off-by: Javier Miralles Rancaño 68760931+FlagshipDev@users.noreply.github.com

…g a compile

Five items about the same thing — what somebody sees before Hullwork works for them — and every one
of them found the product already knew the answer and was not saying it.

## `init` says what *you* need, not what everybody needs

It wrote a 120-line environment file with nineteen empty variables and printed the same five
numbered steps to every reader. Those steps were the union: an instance that only ingests errors
needs four of the nineteen, one that attempts fixes needs seven, and nothing said which reader was
which.

It now asks five questions — enter answers all of them — writes what you gave it, and reports what
is still missing **for the capabilities you asked for**, each with what it buys. Four lines instead
of nineteen blanks. No question asks for a secret: they ask which things exist, never what they are,
and the report never prints a value.

## The checks arrive before the containers, not after

Every check `hullwork doctor` makes now runs during `init`, before anything is built or started.
That was always possible and nobody had noticed: the checks need a database session, and an
in-memory one satisfies both that and the rule that a setup command must not create a database file
in whatever directory you are standing in.

And one check that did not exist anywhere: **does the forge you named actually answer, and what may
your token do there.** `doctor` touches no network — it reported `ok` for a hostname that does not
resolve, because the question it asks is *which forge is this configured for*. So the first sign
that a token was wrong used to be `projects add` refusing it.

Three answers, kept apart: reached it and it is fine, reached it and it is wrong, and **could not
reach it from here** — which is a fact about your machine as much as about the forge, is reported as
such, and never sets the exit code. A laptop behind a VPN does not fail your install.

`init` is safe to run again and again; the second run is the report on its own, which is what you
want after pasting a credential. It reaches the network only when a forge is configured, and its
help says so.

## Step one is no longer a compile

Two compose files shipped, and the one written for real deployments was the one that needed a
checkout: it built from source and did not contain the string `ghcr.io` anywhere, while the file
that pulls the published image was labelled the *evaluation* stack. So the documented path was clone
the source, build 500 MB, and never find out a published image exists.

`init` now writes a compose file that pulls a pinned published image — the version of the image that
wrote it, which is provably one you just pulled. Building is still there, explicit, four commented
lines and the sentence saying when you want it: when you are changing Hullwork's own code, which is
what the build variable was always for. It is no longer among the things the report says a person
must supply.

The gateway that observes and seals model traffic used to run from a hardcoded image name, whose own
comment named the assumption that pulling breaks — *the image this installation built*. It now
follows the image the instance runs.

## What is not claimed

Nobody outside this project has installed Hullwork, and this changes what the first hour looks like
rather than proving anything about it. The measurements here are of the commands, not of a stranger
using them. `docs/status.md` remains the honest scope.

Signed-off-by: Javier Miralles Rancaño <68760931+FlagshipDev@users.noreply.github.com>
@FlagshipDev
FlagshipDev merged commit af9cdd1 into main Aug 10, 2026
4 checks passed
@FlagshipDev
FlagshipDev deleted the publish/2026-08-10-4b7696e branch August 10, 2026 09:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant