Genome Commands

An agent’s genome is the set of genes it runs and how they are composed. rotifer genome export writes it to a Genome Blueprint file (.rgenome); rotifer genome import rebuilds the agent from that file, on another machine or in another project.

A Blueprint holds references, not code. Each gene is identified by its content-derived gene ID, with a hint for where to find it in the Registry and, unless the export is locked, a capability query, so the receiver can find an equivalent gene if the original is no longer available.

rotifer genome export

Export an agent’s genome as a Blueprint.

rotifer genome export <agent> [options]

Arguments:

Argument	Required	Description
agent	Yes	Agent name or ID

Options:

Flag	Description
-o, --output <file>	Output file (default: <agent>.rgenome)
--lock	Reference genes by ID only and write no capability queries. The receiver gets exactly these genes or nothing.
--min-fitness <n>	Minimum fitness in each capability query (default: 0.3)
--min-vg <n>	Suggested minimum V(g) for whoever imports it, in [0.5, 1.0)
-d, --description <text>	Description stored in the Blueprint

What it does:

1. Reads the agent’s genes from this project. Every gene must be compiled (rotifer compile), because the Blueprint identifies each gene by the ID of its compiled content.
2. Writes, for each gene: its gene ID and role, the composition, where to find it in the Registry (if it was published to or installed from there), and, unless --lock is set, a capability query (domain, input and output schema, minimum fitness).
3. Scans the file for credentials (key names, value patterns, entropy) before writing it. If anything is found, the export stops and nothing is written.

It works offline and needs no login. If you are logged in, your username is recorded as the author.

Example:

$ rotifer genome export demo-agent
  Genome Export
  ───────────────
  Agent: demo-agent
  Composition: Seq
  Mode: capability + gene IDs
    genesis-web-search: v2:d032a9e5…  Native
    genesis-code-format: v2:8694260c…  Native
✓ Credential scan passed (key names, value patterns, entropy)
✓ Wrote ./demo-agent.rgenome

Notes:

• A gene that was never published or installed from the Registry can only be matched by capability on the receiving side. The export warns about it.
• A Wrapped gene cannot be installed from the Registry by the receiver; only a Native or Hybrid gene found by capability can take its place. The export warns about these as well.
• A gene without a domain gets a warning too, because its capability query cannot be matched.

---

rotifer genome import

Rebuild an agent from a Genome Blueprint.

rotifer genome import <file> [options]

Arguments:

Argument	Required	Description
file	Yes	Blueprint file (.rgenome)

Options:

Flag	Description
--pinned	Install exactly the genes the Blueprint names; skip capability matching
--dry-run	Resolve every role and print the plan; install nothing
--yes	Accept substitutes from other authors without asking
--name <agent>	Name for the new agent (default: the Blueprint’s)
--min-vg <n>	V(g) threshold for capability picks, in [0.5, 1.0). The strictest of this, the Blueprint’s suggestion and the default 0.7 wins.
--max-eval-age <days>	Ignore Arena evidence older than this (default: 90)

How each gene (role) is resolved:

1. With --pinned, or when the Blueprint has no capability query for the role: the exact version the Blueprint names is installed from the Registry.
2. Otherwise the Registry is searched by capability. A candidate must be in the verified Arena tier and not invalidated; must not be Wrapped; must have a published WASM artifact and the same schemas as the original; must meet the fitness and V(g) thresholds; and must have Arena evidence newer than --max-eval-age days.
3. If no candidate qualifies, it falls back to the exact version.
4. A substitute from a different author needs your confirmation. In a terminal it asks for each role; in a script it is not taken (the exact version is used instead) unless you pass --yes.

Nothing lands in your project until every role checks out. The genes are fetched into a staging directory first and each one’s ID is verified, against the Blueprint for an exact version, or against the Arena evidence for a substitute. Only then are the genes copied into your project and the agent created. If anything fails, nothing is imported.

Example:

# See the plan first: which gene each role gets and why, which candidates were rejected
$ rotifer genome import demo-agent.rgenome --dry-run

# Then import under a new name
$ rotifer genome import demo-agent.rgenome --name demo-copy

If a role can be neither matched nor installed exactly, the import stops and names it:

$ rotifer genome import demo-agent.rgenome --dry-run
✗ Role 'genesis-web-search': alice/genesis-web-search@0.2.0 is not in the Registry (unpublished, or never published)

Notes:

• An identical gene already in your project is reused. A different gene with the same name stops the import.
• If an agent with that name already exists, pick another with --name.
• Add --json for machine-readable output.