# Naming conventions (first-party vs vendored)

This repository distinguishes **first-party** Bare OS sources from **vendored** third-party trees. Governance wording rules and identifier style apply differently in each.

## First-party trees

Subject to [kernel program](kernel-program.md) vocabulary, CI terminology checks (`scripts/verify-banned-terminology.mjs`), and the alias matrix ([Naming alias matrix](../docs/reference/naming-alias-matrix.md)):

- `packages/bare-os-booter/`, `packages/bare-os-protocol/`, `packages/bare-os-coreutils/`, `packages/bare-os-seeder/` (except its vendored subtree below)
- `kernel/` except `kernel/lib/bare/`
- `docs/`, `handbook/`, `developer-guide/`, `users-manual/`, `scripts/`

Prefer **boot stage** / **boot step** / **capability word** language in new prose and APIs. When renaming symbols, keep **deprecated aliases** until the published deprecation window ends (see [Naming migrations](naming-migrations.md)).

## Vendored exception

`kernel/lib/bare/` (mirrored under `packages/bare-os-seeder/kernel/lib/bare/`) is **vendored**. It may contain legacy English tokens, upstream identifiers, and MIME-adjacent strings. The terminology verifier **skips** this subtree entirely.

## Environment variables

- Prefix operational flags with `BARE_OS_`.
- Prefer `*_BOOT_SKIP_STAGES` over legacy `*_BOOT_SKIP` spellings where both exist; document aliases in the naming alias matrix.

## `ctx` methods

- New APIs use **`bareOs…`** camelCase on the injected context object.
- Canonical boot hook names: **`bareOsRegisterBootStepHook`**, **`bareOsInvokeBootStepHooks`**, **`bareOsEmitBareBootStepHint`**. Legacy `**…BootPhase…`** methods remain as thin wrappers.

## `/proc` and wire-visible paths

- Do not remove legacy proc filenames or JSON keys without a **versioned alias** period. Internal variable names may use neutral wording while on-disk names stay stable.

## Extension and capability identifiers

- Use stable string keys aligned with `packages/bare-os-protocol` capability documentation and `docs/schemas/` where applicable.