Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Bluefin Server — Agent Entry Point

Bluefin Server is an FSDK-based, image-based Linux server OS. It produces:
Bluefin Server is an image-based Linux server OS. It produces:
- an immutable XFS DDI OS payload (`oci/bluefin-server-ddi.bst`)
- an offline, systemd-native installer raw disk (`oci/bluefin-server-installer.bst`)
- an optional k0s `systemd-sysext` (`oci/k0s-sysext.bst`)
Expand All @@ -18,7 +18,7 @@ Bluefin Server is an FSDK-based, image-based Linux server OS. It produces:

## Hard rules

1. Compose from FSDK 26.08 `components/*`. Never use `platform.bst`.
1. Installer image composes from FSDK 26.08 `components/*`; OS payload may import Flatcar binaries pinned by digest. Never use `platform.bst`.
2. Keep the CPU baseline broad: no `x86_64_v3`.
3. Installer must stay `systemd-sysinstall`-native and `systemd-repart`-based; no custom installer scripts or non-native installers.
4. Deliver k0s as an optional `systemd-sysext`; never bundle Kubernetes or container runtimes into the base OS DDI.
Expand Down
77 changes: 2 additions & 75 deletions docs/DOCUMENTATION_OVERHAUL_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,82 +201,9 @@ These rules are enforced by `.github/scripts/docs-checks.py` and must be honored

## 6. `AGENTS.md` target contents

The existing `AGENTS.md` is already AAIF-aligned. The target content below keeps the current shape, with only minor wording consistency polish.
The existing `AGENTS.md` is already AAIF-aligned, and its current content *is* the target: project overview, “What agents should know first”, hard rules, build/test commands, skill routing, documentation conventions, boundaries, and a verification checklist.

```markdown
# Bluefin Server — Agent Entry Point

Bluefin Server is an FSDK-based, image-based Linux server OS. It produces:
- an immutable XFS DDI OS payload (`oci/bluefin-server-ddi.bst`)
- an offline, systemd-native installer raw disk (`oci/bluefin-server-installer.bst`)
- an optional k0s `systemd-sysext` (`oci/k0s-sysext.bst`)

## What agents should know first

1. Read this file.
2. Load [`docs/skills/index.md`](docs/skills/index.md) to route to the skill for your task.
3. Never guess label names, workflow secrets, or infrastructure hostnames — check the relevant skill.

## Hard rules

1. Compose from FSDK `components/*`. Never use `platform.bst`.
2. Keep the CPU baseline broad: no `x86_64_v3`.
3. Installer must stay `systemd-sysinstall`-native; no custom installer scripts or non-native installers.
4. Deliver k0s as an optional `systemd-sysext`; never bundle Kubernetes or container runtimes into the base OS DDI.
5. Boot entries use GPT `PARTUUID`; never hardcode device paths.
6. One canonical source per fact; do not duplicate content across docs.

## Build / test commands

All `just` targets run BuildStream inside the FSDK `bst2` container via `just bst`; BuildStream is not installed locally.

| Command | Purpose |
|---|---|
| `just validate` | Merge-contract graph check — run this on every change. |
| `just build-ddi` | Local OS DDI payload build. |
| `just export-ddi` | Export DDI artifacts to `dist/ddi/`. |
| `just build-installer` | Local full installer build. |
| `just export-installer` | Export installer + UKI to `dist/`. |
| `just build-sysext` | Build the k0s `systemd-sysext`. |
| `just export-sysext` | Export sysext artifacts to `dist/sysext/`. |
| `just show-me-the-future` | Local QEMU installer smoke test. |

## Skill routing

| Task | Skill |
|---|---|
| Build or debug the installer / DDI | [`docs/skills/ddi-installer.md`](docs/skills/ddi-installer.md), [`docs/skills/ddi-installer-build.md`](docs/skills/ddi-installer-build.md) |
| Factory role, k0s sysext rationale, lab integration | [`docs/skills/factory-integration.md`](docs/skills/factory-integration.md) |
| Work with `systemd-sysext` / `systemd-confext` | [`docs/skills/systemd-sysext-extensions.md`](docs/skills/systemd-sysext-extensions.md) |
| Build or ship the k0s sysext | [`docs/skills/k0s-sysext.md`](docs/skills/k0s-sysext.md), [`docs/skills/k0s-sysext-ops.md`](docs/skills/k0s-sysext-ops.md) |
| Update the FSDK pin / versioning | [`docs/skills/bump-fsdk-version.md`](docs/skills/bump-fsdk-version.md) |
| CI workflows, action SHA pinning | [`docs/skills/ci-tooling.md`](docs/skills/ci-tooling.md) |
| Release signing / sysupdate trust | [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) |
| Credential sealing with TPM2 | [`docs/skills/tpm2-credential-sealing.md`](docs/skills/tpm2-credential-sealing.md) |
| System containers (`machinectl`) | [`docs/skills/system-containers.md`](docs/skills/system-containers.md) |
| Cut bloat / avoid over-engineering | [`docs/skills/avoid-over-engineering.md`](docs/skills/avoid-over-engineering.md) |
| Add or refactor skills | [`docs/skills/skill-improvement.md`](docs/skills/skill-improvement.md) |

## Documentation conventions

- Update only the skill that matches your change.
- Keep `AGENTS.md` small; do not list deep context here.
- Remove `TODO/FIXME` and work-in-progress markers before merging; move unfinished work to issues.
- Use Conventional Commits. For doc-only changes: `docs:`.

## Boundaries

- Do not add Containerfiles or shell-based installers.
- Do not hardcode block device paths in boot configuration.
- Do not put Kubernetes or debug tooling in the base DDI if it can live in a sysext or system container.
- Do not duplicate a fact already in a skill.

## Verification

- [ ] `just validate` passes.
- [ ] Any changed skill is listed in [`docs/skills/index.md`](docs/skills/index.md).
- [ ] No new internal-only hostnames or proprietary names appear in `AGENTS.md` or skills.
```
Per hard rule 6 in [`AGENTS.md`](../AGENTS.md), that content is not restated here; read the file directly, and land hard-rule changes only there.

---

Expand Down
47 changes: 47 additions & 0 deletions docs/superpowers/specs/2026-09-13-flatcar-binary-imports-adr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# ADR: Scope FSDK composition to the installer

**Status:** Accepted

## Context

Bluefin Server currently builds the installer and installed OS payload in one
FSDK-oriented composition model. The installed OS already imports Flatcar's
kernel and ZFS system extension as pinned binary artifacts, and the Flatcar
base migration extends that model to the OS payload's userspace and runtime
system extensions.

The installer still needs FSDK because it relies on `systemd-sysinstall`, which
Flatcar does not ship. The installed OS payload does not need that tool after
the DDI is built; the installer writes the DDI by `CopyBlocks=`, a byte-level
contract that does not inspect the payload's userspace.

## Decision

Hard rule 1 is scoped to the installer image: installer elements continue to
compose from FSDK 26.08 `components/*` and must not use `platform.bst`.

The installed OS payload may import Flatcar OS and system-extension binaries
when the imported artifact is pinned by digest in BuildStream. This matches the
existing `flatcar/flatcar-kernel.bst` and `flatcar/flatcar-zfs.bst` model and
keeps the OS payload on a single upstream ABI domain as the Flatcar migration
lands.

Hard rules 2-6 remain active. The CPU baseline remains broad, the installer
stays `systemd-sysinstall`-native and `systemd-repart`-based, boot entries keep
using GPT `PARTUUID`, and duplicated sources of truth remain prohibited.

## Rejected alternatives

### Rebuild Flatcar from source in BuildStream

Rejected. Flatcar is a Gentoo/portage-based cross-build. Reproducing that build
inside this repository's BuildStream project would create a second upstream
build system with large maintenance cost and no additional local contract over
a digest-pinned upstream artifact.

### Keep the status quo hybrid

Rejected. Keeping FSDK userspace in the OS payload while importing Flatcar
kernel and ZFS artifacts preserves the ABI split that the migration is meant to
remove. It also keeps `ID=flatcar` as a compatibility fiction rather than the
installed OS payload's real identity.
Loading