docs

Imported from pkgforge-dev/docker-bsd (docs/AGENTS.md). Install upstream with npx skills add pkgforge-dev/docker-bsd --skill docs. Copyright stays with the author.

AGENTS.md

docker-bsd builds OCI images for FreeBSD, NetBSD and OpenBSD from each project's own published userland, and works on the harder half: running one. A BSD userland needs a BSD kernel, so this repository also holds the measured routes from an ordinary Windows or Linux host to a booted BSD, and the experiments that establish which of them actually work.

⭐ This file is a router, and it is the only agent entry point in this repository. Not one per directory, not a second one in the root. It restates nothing written elsewhere, so the two cannot fork. Everything binding is linked, and the link is the authority: reading a row in a table here is not reading the rule.

HUMANS.md is the other side of it: what a person runs, and the permissions block that says what you may do without asking.

Start here, every session

⭐ Read ../TODO/SUMMARY.md in full. It is the brief: one table plus the findings, and it is the fastest orientation into what the last session actually did. It is a snapshot, not an authority.

⭐ Then ../TODO/PROGRESS.md. It is the only file that carries a work order. Nothing else does: not this file, not ../README.md, not ../TODO/INDEX.md, which is a sortable list and not an order. PROGRESS.md is rewritten at the beginning and the end of every session.

Then run the probe, because a different machine changes what this session can prove:

sh scripts/doctor/doctor.sh

pwsh -NoProfile -File scripts/doctor/doctor.ps1

Then read what this task routes you to, below. Not everything, and not less.

⛔ And before you design anything, check whether it is already mined

⭐ 37 external projects have been read for this repository, in four sweeps, with their trackers, and written up in ../HISTORY/references/findings.md and ../HISTORY/references/usable.md.

⛔ This is not optional background and it is not "studying another project". It is prior art for the work in front of you, and the entries in ../TODO/ name the sections that bear on each of them. ⚠ A session that skipped it hand-wrote a provisioning mechanism that upstream already ships, which is recorded under INF-09.

The routing table

⭐ This table is the reason this file exists. Find the row for the work in front of you and read what it names, in full.

⛔ Read what the row names in full. Not grepped, not skimmed, not recalled from a previous session. The routing exists so the reading is small enough to actually do. ⚠ When two rows apply, read both: the union, not the shorter one.

The four things this repository will not bend on

Each links to where the real rule lives.

1. ⛔ A negative result is a result, and it gets committed

⭐ The experiment that FAILED is why the one that worked, worked. Booting smolBSD under the Windows hypervisor failed, and locating why is what made the FreeBSD boot succeed an hour later. An experiment deleted because it did not work costs the next session the same day. ../experiments/README.md.

2. ⛔ Measured, or labelled. Never estimated

⚠ A number on a report that was not measured is worse than a blank, because a blank gets checked. ⛔ And a correlation is not a cause. This repository published one tidy explanation and withdrew it inside the same session, and the correction is written under the claim rather than over it. conventions/prose.md.

3. ⛔ One fact, one home

⛔ No measured number appears in two documents. Every measurement lives once, where it was taken, and everywhere else points at it. A value in two places is a value that will disagree with itself, and the copy a reader trusts is the wrong one. conventions/docs.md.

4. ⛔ Read the exit code from the process that produced it, unpiped

cmd | tail then $? reads tail's status, so a guard that failed reads as green. That shipped here twice. conventions/forbidden-patterns.md.

What must not be touched, and why

The gates

sh scripts/common/check-gate.sh --fast

sh scripts/common/check-gate.sh

sh tests/run.sh

⚠ --fast skips check-twins, which runs both halves of every .sh/.ps1 pair and is most of the wall time. ⛔ A skipped check is not a passed check, and the gate says so rather than counting it.

⛔ The suites prove the code and nothing else. They are blind to the platform's real behaviour, which is why methodology/gate.md has three parts and not one.

⭐ When a human wrote it, say so rather than fixing it silently

You will follow conventions/ mechanically. A human contributor may never have read them, and that is normal.

⛔ So when you find a script, document, test or workflow here that breaks a convention, do three things and stop:

1. Name it. The file, the line, and the rule it breaks.
2. Say what you would change, concretely.
3. Offer. Then wait.

⛔ Do not silently rewrite it. The person who wrote it may have had a reason that is not written down, and a rule applied over an unstated reason is how a working thing gets broken tidily. ⚠ This repository has examples: several lines in experiments/ look wrong and are the fix for a specific measured trap.

⛔ And do not silently copy it either. Finding one convention-breaking file is not permission to write a second. If the existing style and the written rule disagree, the written rule wins and the disagreement is the finding.

What this repository is not

⚠ Stated because each has been assumed at least once.

• ⛔ It is not a way to run BSD binaries on a Linux kernel. That exits 139, a SIGSEGV, and no binfmt_misc or qemu-user setting reaches it. ../README.md opens with the measurement.
• ⛔ It does not rebuild what upstream already publishes. FreeBSD publishes its own OCI images and this repository verifies and loads them.
• ⚠ It is not finished. LIMITS.md is the honest list, and it is meant to shrink.