Module setup 

Engine setup from global CLI flags. Produces an Engine synchronously (no tokio) for the CLI to call into directly.

Post-rebuild there is one workspace marker: .memstead/workspace.toml at the workspace root. The mem-repo Cargo feature decides which engine factory consumes it — full routes through memstead_git_branch::workspace_store::engine_from_workspace_root (git-branch backends plus folder + archive), lean routes through memstead_base::Engine::from_workspace_root (folder + archive only).

CliEngine wraps either flavour; subcommands match-dispatch on it. The WorkspaceShape variant is retained so the lean build can still surface an actionable “this is the lean binary, your workspace has git-branch mounts” error when the operator points a lean binary at a full workspace — the shape tag is derived from mem-repo/.git co-existing with the marker rather than the marker itself.

Structs

CliContext

Global CLI state: shared flags + a lazily-initialized Engine.

ShapeDisclosure

The three-part disclosure a workspace-creating command owes its caller: which shape was just made, one concrete thing that shape cannot do, and the exact command that produces the other one.

Enums

CliEngine

Engine instance + the workspace flavour it serves. Subcommands match on the variant to call the right engine API; the read-side store accessor (engine.store()) lives on both flavours so simple read commands can share most of their bodies.

WorkspaceShape

Workspace flavour resolved from cwd. Subcommands dispatch on this to pick the right engine accessor.

Constants

WORKSPACE_NOT_INITIALISED_CODE

Structured-code constant for the missing-workspace exit envelope. Surfaced on both --json output (under the code key in details) and as the Display body of the underlying CliError. Scripts and agents branch on this stable token; the human prose (which mentions the recovery command) is the message and can be adjusted without breaking the contract.

WORKSPACE_RECOVERY_COMMAND

Recovery command suggested when no .memstead/workspace.toml is reachable from cwd. memstead mem-repo init in the full build (this binary speaks mem-repo); memstead init in the lean build. The structured hint.recovery_command field carries this token verbatim so an agent can re-exec it.

Functions

boot_error_to_cli

Lift a memstead_base::BootError into the typed CLI envelope. The boot seam previously flattened these through anyhow, so the main downcast missed them and every boot failure surfaced as code: INTERNAL with no next step (plenum 2026-08-06/07, expertise 2026-08-07). The typed material lives on memstead_base::BootError::code; this function only wraps it in the CLI’s exit shape. The message is memstead_base::BootError::surface_message verbatim — identical on the MCP server’s boot diagnostics for the same broken workspace.

cli_client_id

The memstead-cli@<version> client identity stamped into the commit body’s Client: provenance trailer. Shared by every CLI mutation path so the trailer is uniform across create / update / relate / rename. Un-gated (unlike cli_ctx_with_note) because the relate path passes the client to relate_entity directly rather than through a CommitContext, and that path compiles on both flavours.

cli_ctx

Provenance bundle for every CLI-initiated mutation. Actor::Cli + memstead-cli@<CARGO_PKG_VERSION>. The Tool: trailer stays None: CLI subcommands aren’t MCP tools and the commit subject (memstead: create …) already carries the action verb — a second taxonomy would drift.

cli_ctx_with_note

Provenance bundle carrying an optional agent-authored --note. The note rides into the same payload slot the MCP note parameter uses; the engine’s require_notes policy gate fires NOTE_MISSING symmetrically across both surfaces.

find_filesystem_workspace_root

Compatibility alias for find_workspace_root — kept so existing CLI subcommands (export, changes, …) that historically routed through the lean-flavour walker continue to compile. Both walkers now find the same marker; the alias is intentional for call-site clarity (find_workspace_root reads as the canonical surface; find_filesystem_workspace_root documents the folder-mount-only intent of its caller).

find_workspace_root

Walk upward from start looking for the first ancestor that contains .memstead/workspace.toml (the post-rebuild workspace marker). Returns the first ancestor directory carrying the marker, or None if the walk reaches filesystem root without finding one.

full_engine

Build the unified memstead_base::Engine for a mem-repo-shaped workspace. Delegates to engine_from_workspace_root which handles layout detection, mount enumeration, schema resolution, and readMems hydration in one pass.

memstead_program

Resolve the running memstead binary to something the reader can actually type. Bare memstead when that name on PATH resolves to this very binary; otherwise the path we were invoked as.

shape_disclosure

The disclosure for a shape.

shape_disclosure_lines

Convenience for callers that only render markdown.

shell_quote

Render a string as one POSIX shell word. Bare when every character is safe unquoted; otherwise single-quoted, with embedded ' closed and re-opened the POSIX way ('\'').

workspace_not_initialised_error

Build the typed WORKSPACE_NOT_INITIALISED exit envelope. Goes through CliError so the top-level main downcast lifts the code + hint fields into the JSON output.