Modules Overview

TL;DR: Reference table of all genesis-vibes modules with key types, traits, and entry points.

Module Map

envelope

Signature: genesis::envelope

Structured CLI output envelope. Every command returns an Envelope<T>.

Key Types

Functions

Constructors

CLI version ownership contract

cli_version is caller-supplied at construction — the first argument to every constructor. It must be the version of the tool that emits the envelope (typically env!("CARGO_PKG_VERSION") in the downstream tool’s own crate).

Genesis-vibes never injects its own package version: the misleading genesis-derived CLI_VERSION default was removed in the version that introduced this change. There is no zero-argument constructor that silently emits genesis’s version — pass your own version explicitly.

Migration path (for tools adopting the new contract):

1. At each Envelope::success / success_with_tx / error call site, add the tool’s own version as the first argument:

   #![allow(unused)]
   fn main() {
   Envelope::success(env!("CARGO_PKG_VERSION"), EnvelopeKind::Ok, data, vec![], vec![])
   }

2. For envelope-producing helpers (GuideOutput::to_envelope, DoctorReport::to_envelope, StatusReport::to_envelope), the cli_version parameter is now required and must be threaded from the caller.

3. Remove any use genesis::envelope::CLI_VERSION — the constant no longer exists.

4. Verify with cargo test that serialized envelopes carry the tool’s own version, not genesis-vibes’ version.

Receipt metadata (opt-in)

Envelope carries an optional receipt: Option<ReceiptMeta> recording the terminal outcome, retry identity, and user-visible evidence of a command run (add-aix-eval-loop D1). It is additive and opt-in:

• Envelopes constructed without with_receipt() serialize byte-identically to pre-receipt output — the receipt key is omitted entirely (golden-file tested in tests/envelope_golden.rs). No downstream change is required.
• TerminalOutcome classifies how a run ended: Success, Failure, Timeout, or Cancelled. Timeout is explicit, not silent failure, and is independent of the envelope’s ok field (a delivered result with a timed-out follow-up is representable).
• attempt: u32 and optional idempotency_key make retries of mutating commands distinguishable. Which commands qualify is a per-tool policy — genesis ships the mechanism, not the policy.
• evidence: Option<String> is a verifiable statement of the user-visible edge (“file X exists at path Y”), not free-form narrative.

#![allow(unused)]
fn main() {
use genesis::envelope::{Envelope, EnvelopeKind, ReceiptMeta, TerminalOutcome};

let env = Envelope::success(env!("CARGO_PKG_VERSION"), EnvelopeKind::Ok, data, vec![], vec![])
    .with_receipt(ReceiptMeta {
        terminal_outcome: TerminalOutcome::Success,
        attempt: 1,
        idempotency_key: Some("deploy-config".into()),
        evidence: Some("file exists at /tmp/out.txt".into()),
    });
}

guide

Signature: genesis::guide

CLI scaffold: verbosity, output format, error handling, and command dispatch.

Key Types

Functions

suggestions

Signature: genesis::suggestions

Self-healing error suggestions and typo detection.

Key Types

Functions

managed_block

Signature: genesis::managed_block

Managed block injector for <!-- NAME:START --> / <!-- NAME:END --> markers in markdown files.

Key Types

Functions

config

Signature: genesis::config

Shared config management with validation and error reporting.

Key Types

Functions

aix

Signature: genesis::aix

AIX artifact generation helpers for llms.txt, llm.txt, and AGENTS.md blocks, plus token-cost estimation and budget-bounded generation (add-aix-eval-loop §2).

Key Types

Functions

Token-cost heuristic

estimate_token_cost uses the chars/4 heuristic (ceiling division) with a documented ±25% error band against typical English prose in cl100k-class vocabularies — good enough for budget arbitration, not for billing. The heuristic name ships inside every TokenCost so an approximation is never mistaken for a tokenizer count. No tokenizer dependency is pulled in.

Budget degradation ladder

Both bounded generators degrade deterministically instead of overflowing or refusing. Granularity steps, in order:

1. at or under budget → byte-identical to the unbudgeted generator
2. truncate descriptions to their first sentence
3. drop optional (Raw) sections
4. drop table content — headings always survive; module names are the floor

The floor artifact is returned even if it still exceeds the budget: a verbose artifact beats a missing one. Existing generate_llms_txt / generate_llm_txt signatures are untouched (golden-file pinned in tests/aix_bounded.rs).

evals

Signature: genesis::evals

Deterministic evaluation harness: scenarios replayed against fake-agent transcripts, with envelope-assertion helpers, reusable checks, distractor fixtures, and the doc-drift blindness check (add-aix-eval-loop §3). No live LLM, no subprocess runner.

Key Types

Functions

Distractors and doc-drift blindness

Distractor files share the replay environment with real fixtures but are registered separately, so checks can tell bait from task material. Presence of a distractor never faults a run by itself — the check decides:

• doc_drift_blindness(bait_cmd) passes when the agent received a parseable envelope from an executed step and never issued bait_cmd (the action only correct per the stale docs). Action-level correctness composes with ok_envelope / agent_followed_hint.
• Doc-following steps fail as agent fault ERR_DOC_DRIFT_BLINDNESS with the distractor path in the reason.
• A scenario without a StaleDocs distractor makes the check a tool fault (misconfiguration), not an agent fault.

ScenarioReport serializes to JSON (name, passed, failures with taxonomy codes, model when attributed) for per-model matrix comparison; run()’s signature is unchanged — attribution happens post-hoc via with_model.

feedback

Signature: genesis::feedback

Agent issue reporting — wraps scratch (error persistence), context (env bundle), redactor (privacy), and gh (GitHub issue creation) into a single command.

Key Types

Functions

Issue title derivation

The title always starts with [{kind}] . What follows is resolved by precedence:

1. FeedbackArgs::with_title() / the downstream tool’s --title flag — wins over everything.
2. First stdin line, when the piped input is multi-line (the remainder becomes the ## Description body).
3. auto-reported error: {command} on the --from-last-error path.
4. Generic feedback report for single-line stdin.

Stdin contract

handle_feedback reads all of piped stdin (read_to_string, not a single line) — multi-paragraph reports are never truncated. A single-line input (including a trailing newline from echo) keeps the generic title and lands verbatim in the Description. Empty input is an error.

Sub-modules

Converting feedback to regression scenarios

Captured feedback becomes a replayable evals scenario (add-aix-eval-loop §4, design D4) — the aix-gap bundle → regression path:

• Scenario::from_feedback_context(bundle, fixtures) embeds the recorded failure signature (command, exit code, footer hint) as the reproduces-recorded-failure check. Bundle-only conversion (empty fixtures) yields a prompt-only scenario; caller-supplied (path, content) pairs become scenario fixtures via the existing fixture mechanism (the converting tool knows which files were in play — genesis never re-snapshots the working tree).
• feedback::from_last_error(tool_name, fixtures) wraps scratch::read_last_error; a missing record returns the typed ConversionError::NoScratchRecord, never a panic.
• Conversion + replay run in-process: no LLM call, no subprocess runner.

suite_linter

Signature: genesis::suite_linter

Suite-wide config lint checks. Foundation for the doctor module.

Key Types

Functions

fixture

Signature: genesis::fixture

Test scratch environments and runners.

Key Types

Fixture builder methods

doctor

Signature: genesis::doctor

Diagnostic framework with auto-fix.

Key Types

cli

Signature: genesis::cli

CLI helpers.

Functions

status

Signature: genesis::status

Cross-tool status dashboard.

Key Types

scaffold

Signature: genesis::scaffold

Init scaffolding builder.

Key Types

Scaffold builder methods

discovery

Signature: genesis::discovery

Tool discovery via .genesis/tools.toml manifest.

Key Types

Functions

git

Signature: genesis::git

Shared read-only git plumbing: one subprocess-based module for the repo queries every suite tool previously re-implemented with drift. Read-only only — no git init/add/commit (write paths stay with callers), no hook wiring (git_hooks owns that), no git library (the git binary is spawned as a subprocess).

Key Types

Functions

Policy-aware variants

Every named helper that spawns git has a *_with_policy(root, ..., policy) variant taking [EnvPolicy] as its last argument, sharing one internal implementation with the plain variant. The default stays Inherit because hook harnesses legitimately inject GIT_DIR et al.; call the variant with EnvPolicy::StripHookContext when running inside a git hook (e.g. the dont bd hooks) and the repository must be discovered from root alone.

git_hooks

Signature: genesis::git_hooks

Shared git-hook primitives consolidating overlapping mechanics from three donors (pretender, wai, espectacular). Contains only git-hook mechanics — consuming tools pass their own gate commands, markers, and block contents as parameters (guard-tested boundary).

Key Types

Functions

update_check

Signature: genesis::update_check — feature-gated behind update-check

Crates.io update availability checks for dependent binaries. Opt in by enabling the feature on the consumer’s genesis-vibes dependency (update-check = [...]); nothing activates at runtime otherwise.

Design contract ([genesis-2ex])

• Binaries, not libs, notify. Call check() with your own published crate name and installed version — genesis never checks itself from inside a dependent. The crate name must match the published crates.io package exactly: a mismatch 404s and fails silent by design (e.g. a crate published as wai-cli must not pass "wai").
• Cached-passive. At most one fetch per cache TTL (default 7 days, DEFAULT_TTL_SECS); results cached at <cache>/genesis/update-check/<crate>.json, honoring XDG_CACHE_HOME.
• Fail-silent. Any error — network, timeout, corrupt cache, unwritable cache dir — degrades to None. Never panics, never blocks meaningfully (2s connect / 5s total: CONNECT_TIMEOUT, TOTAL_TIMEOUT), never produces user-facing errors.
• CI-aware. CI=true (or 1) or GENESIS_NO_UPDATE_CHECK=<non-empty> skips the check entirely, before any IO.
• Rate-limit polite. crates.io 403/429 responses double the cache TTL and send a descriptive User-Agent.
• Scheme-agnostic versioning. Comparison is current != latest with yanked and semver pre-release versions filtered out — calendar versions need no special-casing.

Key Types

Functions

Validation and debugging

• Crate names are validated (is_valid_crate_name): non-empty, ASCII alphanumeric plus - and _ only — invalid names return None without IO.
• GENESIS_UPDATE_CHECK_DEBUG=1 emits one stderr line per skip/fail reason ([genesis-4mq]) — de-risks silent 404s while wiring a dependent.
• Minimal wiring in a binary’s main:

#![allow(unused)]
fn main() {
if let Some(info) = genesis::update_check::check(
    env!("CARGO_PKG_NAME"),
    env!("CARGO_PKG_VERSION"),
) {
    eprintln!("{}", genesis::update_check::notice(&info));
}
}

env!("CARGO_PKG_NAME") guarantees the crate name matches the published package — hardcoding a name invites exactly the silent mismatch the design contract warns about.