Usage

Runnable workflows for common eforge tasks.

Mapping a new project from scratch

Start from zero on any codebase regardless of whether forge is managing it.

# install
pip install eforge

# bootstrap observation graph
cd your-project
eforge init

# add your first nodes
eforge node add "AuthService" --kind code/class -y
eforge node add "UserTable" --kind data/table -y
eforge node add "LoginScreen" --kind ui/screen -y

# wire relationships
eforge node link "AuthService" "UserTable" \
  --rel persists-to -y
eforge node link "LoginScreen" "AuthService" \
  --rel depends-on -y

# see what you have
eforge node list
eforge node inspect "AuthService" relations

Bootstrapping from an existing forge manifest

If the project already has a .forge/manifest.yaml, import all declared nodes in one command.

# bootstrap from manifest (batch, ~1s for 350 nodes)
eforge node import-manifest

# all manifest nodes are now DevNodes with manifest_ref set
eforge node list --status graduated

# inspect any node — shows declaration + observation context
eforge node show "module/auth.session"

# forge inspect also shows observation layer
forge inspect module/auth.session

Using schemas to capture typed properties

Built-in schemas prompt for the right properties automatically. Project local schemas extend the vocabulary.

# see available schemas
eforge schema list

# add a node with schema prompts
# (interactive: asks lifecycle, owned_state, disposes_on)
eforge node add "GameSession" --kind architecture/session

# add with -y to skip prompts and fill in later
eforge node add "GameSession" --kind architecture/session -y
eforge node show "GameSession"

# create a project-local schema for your domain
eforge schema create game/phase
# prompts: description, properties (name, type, required)
# saves to .eforge/schemas/domain/game/phase.yaml

# use your new schema
eforge node add "DrawPhase" --kind game/phase -y

Notes, tasks, and structured errors

Attach reasoning to nodes and track work without leaving the terminal.

# add a note explaining a decision
eforge node note "GameSession" \
  "route-scoped, not app-scoped — fixes cross-game bleed" -y

# flag a node that needs attention
eforge node mark "AsyncController"

# see marked nodes
eforge node list --marked

# add a task linked to this area
eforge task add \
  --title "Fix AsyncController lifecycle scope" \
  --kind framework --priority high -y

# list open tasks
eforge task list

# look up an error code from eforge output
eforge error show OBS-001
eforge error search "manifest"

Using eforge alongside full forge

When the project uses both tools, the bridge layer connects them automatically.

# declare a new manifest node (creates DevNode too)
forge manifest add module/auth.guards \
  --path src/lib/auth/guards.ts \
  --kind module --domain AUTH -y

# DevNode is created with manifest_ref set
eforge node show "module/auth.guards"

# forge inspect shows both planes
forge inspect module/auth.guards

# orient shows observation summary
forge orient
# Observations:
#   nodes: 12 total  (8 graduated, 4 observed)
#   tasks: 3 active
#   marked: AsyncController

# full observation graph context in JSON
forge orient --json | python3 -m json.tool \
  | grep -A 10 "observations"