Discovery Precedence Flowchart

This diagram shows how commands are discovered and how command name collisions are handled across sources.

Discovery Flow

Conflict Resolution

When names collide, Invowk handles two different cases:

Resolution Rules

Case	Behavior
Same full command name discovered in multiple sources	First discovered source wins (precedence order)
Same simple command name across different sources	Mark ambiguous; user must disambiguate (@source / --ivk-from)

Discovery precedence order:

1. Current directory invowkfile (./invowkfile.cue)
2. Local modules (./*.invowkmod)
3. Configured includes (module paths from config.Includes)
4. User commands directory (~/.invowk/cmds/*.invowkmod, modules only, non-recursive)

Vendored modules (invowk_modules/) are scanned one level deep for each discovered module source.

Module Discovery Details

Required Module Fields

// invowkmod.cue
module: "com.example.mymodule"  // RDNS naming convention
version: "1.0.0"                // Semantic version

// Optional
description: "My useful module"
requires: [
    {
        git_url: "https://github.com/org/repo.invowkmod.git"
        version: "^1.0.0"
    }
]

Dependency Resolution

Transitive Dependency Visibility

This visibility check applies to declared depends_on.cmds dependencies during static validation. It does not intercept arbitrary subprocess calls made at runtime.

From	Can Access	Cannot Access
Module A	A's commands, B's commands	C's commands (transitive)
Module B	B's commands, C's commands	-
Root invowkfile	Own commands, direct deps	Transitive deps

Why this restriction?

• Prevents implicit coupling to transitive dependencies
• Makes dependencies explicit in each module
• Enables dependency upgrades without breaking consumers

Includes Configuration

Additional modules are configured in the resolved global config file:

includes: [
    {path: "/opt/company-invowk-modules/tools.invowkmod"},
    {path: "/home/shared/invowk/shared.invowkmod"},
]

Entry Processing Order

Discovery Caching

Common Discovery Issues

Problem: Command Not Found

Problem: Wrong Command Version

Debug Commands

# List all discovered commands with sources
invowk cmd --ivk-verbose

# Validate workspace discovery (reports all diagnostics)
invowk validate

# Validate a specific module
invowk validate ./mymodule.invowkmod

Related Diagrams

• Command Execution Sequence - What happens after discovery
• Runtime Selection Flowchart - How runtimes are chosen
• C4 Container Diagram - Discovery component context