Bootstrapr

Bootstrapr applies, updates, and checks AxLabs bootstrap conventions in an existing directory. It keeps Bootstrapr-owned guidance current while preserving repository-owned context. Operations are deterministic and offline: Bootstrapr does not inspect a repository semantically, call a network service, or use a language model.

Prerequisites

Node.js 22 or newer.

Run

Pin the package version in automation so a later Bootstrapr release cannot change repository conformance unexpectedly:

npx @axlabs/[email protected] init [directory]
npx @axlabs/[email protected] update [--dry-run] [directory]
npx @axlabs/[email protected] check [directory]

CI and agents should add --yes to avoid the npx install confirmation prompt. pnpm dlx @axlabs/[email protected] <command> is equivalent for pnpm users. A directory defaults to the current working directory and must already exist.

Commands

init

init adopts an unmanaged repository directly at the latest repository schema. It installs the fully managed .axlabs/INITIALIZE.md and decision-convention files, creates or augments AGENTS.md, and writes authoritative .axlabs/state.json last. It does not replay historical migrations.

First adoption adds an AXLABS INITIALIZATION: INCOMPLETE marker to repository-owned AGENTS.md. The managed pointer directs the invoking agent to .axlabs/INITIALIZE.md, where it is told to inspect repository evidence, fill repository-owned context, and remove the marker.

init is adoption-only: it transitions a repository from unmanaged to managed exactly once. Repeating it on a current repository is an error and changes nothing. An older managed repository is directed to update; a newer schema requires a newer CLI; malformed state is never reinterpreted as unmanaged. init is not a repair command.

update

update migrates an already-managed repository through every required repository schema in order. For example, a future update from schema 2 to schema 4 executes 2 → 3 and then 3 → 4. The command plans and validates the complete chain before writing, preserves repository-owned content, writes files atomically, and advances authoritative state only after the migration's other changes succeed. A rerun safely completes an interrupted migration.

update --dry-run performs the same validation and reports planned changes without writing files. Conflicting files, modified managed content, malformed markers, invalid metadata, unmanaged repositories, and repositories newer than the CLI fail without guessing or silently discarding content.

Schema 2 is the first repository format Bootstrapr supports going forward. Package 0.2.1 deliberately provides no migration from the root-marker format used by 0.1.0 or from the initial 0.2.0 schema-2 inventory. Those early repositories require manual reinitialization.

check

check is read-only. It succeeds only when authoritative state describes the current repository schema and managed inventory, fully managed files are current, every required managed block is present and current, markers are well formed, and repository-specific initialization is complete. An older schema is reported as outdated and directs the user to update; a newer schema reports that the CLI is too old.

Ownership and state

Bootstrapr recognizes three ownership forms:

• Fully managed files, currently .axlabs/INITIALIZE.md, docs/decisions/README.md, and docs/decisions/0000-template.md, may be installed during adoption and changed by explicit migrations when their previous content is known.
• Named managed blocks inside AGENTS.md may be added or updated independently.
• Repository-owned content, including everything in AGENTS.md outside managed blocks and actual decision records (0001-* and later), is never replaced by Bootstrapr.

.axlabs/state.json is the authoritative schema-2 repository state. It records the repository schema version plus SHA-256 inventories of fully managed files and named blocks. Package versions and repository schema versions are independent: a package release need not introduce a repository migration.

Durable decisions

The managed AGENTS.md guidance points agents to docs/decisions/ before they change architecture, ownership, compatibility, or established product behavior. The managed README contains the lightweight qualification heuristic, lifecycle, and ownership rules; 0000-template.md is the starting point for repository-owned numbered records. Bootstrapr provides no ADR command, generation, semantic detection, or validation.

Repository-specific decisions live with the repository. Decisions spanning repositories belong in the authoritative project-context repository identified by the repository-owned Project Context section of AGENTS.md, when configured. Work continues locally when no such authority is configured.

Current scope

Version 0.2.1 provides deterministic init, sequential update infrastructure, update --dry-run, and read-only check behavior for existing directories. Schema 2 is the first supported repository format; compatibility with the early root-marker and initial-0.2.0 formats is intentionally omitted. Creating a Git repository, interactive prompts, profiles, automatic inference, and harness-specific adapters remain outside the current scope.