World Monorepo Navigation

Core Concepts

Terminology

• •World Path: Path starting with // (e.g., //areas/tools/tec, //areas/tools/tec/README.md)
• •Zone Path: World Path at the root of a zone (has zone.nix and manifest entry), e.g., //areas/tools/tec
• •Zone ID: Stable identifier (W- + 6 hex chars), defined in //.meta/manifest.json
• •Worktree: A separate working copy of the repo with its own checkout
• •Checkout root: $HOME/world/trees/<treeName>/src

Worktrees

World supports multiple worktrees. The git directory lives at ~/world/git, with worktrees at ~/world/trees/<name>/src.

Common worktrees:

• •root - Default worktree (~/world/trees/root/src)
• •hotfixes - For hotfix work (~/world/trees/hotfixes/src)
• •Custom worktrees for parallel work

World paths (//) resolve relative to the current worktree:

• •In ~/world/trees/root/src/areas/foo → //.meta = ~/world/trees/root/src/.meta
• •In ~/world/trees/hotfixes/src/areas/foo → //.meta = ~/world/trees/hotfixes/src/.meta

Each worktree has its own sparse checkout configuration.

Zone Structure

Zones are NOT nested. Almost everything lives in a zone. Major roots:

• •//areas - Application code
• •//libraries - Shared code
• •//protocols - Schemas
• •//config - Shared configs
• •//.meta - Tectonix build system

Finding Zones

Discover Current Zone

tec resolve .

Returns the //zone/path for the current directory.

List All Zones

tec zone list

Zone Manifest

The source of truth for all zones is //.meta/manifest.json. Use this to:

• •Find zones by name or ID
• •Discover all zones in a specific area
• •Look up zone IDs for external references

Sparse Checkout Management

World uses sparse checkout. Files outside checked-out zones are NOT available on disk. Each worktree maintains its own sparse checkout configuration.

List Checked-Out Zones

tec checkout list

Add a Zone to Checkout

tec checkout add //path/to/zone

Remove a Zone from Checkout

tec checkout remove //path/to/zone

Access Files Not in Checkout

Use git show to read files without adding to sparse checkout:

git show HEAD:path/to/zone/file

Cross-Zone Code Changes

When modifying code across multiple zones:

1. •Identify all affected zones: Search for usages across zones using git show or add zones to checkout
2. •Add zones to checkout: tec checkout add //zone/path for each zone you need to modify
3. •Verify zone dependencies: Check zone.nix for declared dependencies between zones
4. •Make coordinated changes: Update all zones atomically to avoid broken intermediate states
5. •Test across zones: Run tests in each affected zone

Zone Development Environment

Each zone can define commands in dev.yml. Common commands:

• •dev up - Build nix environment (activated via Shadowenv)
• •dev server - Start development server
• •dev console - Interactive console
• •dev test - Run tests
• •dev style - Run linting

To run dev commands: /opt/dev/bin/dev <command>

Navigation Patterns

Finding Code by Domain

1. •Check //areas for application code organized by team/domain
2. •Check //libraries for shared utilities
3. •Check //protocols for API schemas

Finding Dependencies

1. •Look at zone.nix for declared zone dependencies
2. •Search for imports across zones using the manifest

Path Resolution

From a checkout (e.g., $HOME/world/trees/root/src/areas/tools/dev):

• •//.meta refers to $HOME/world/trees/root/src/.meta
• •Paths are relative to the checkout root, not the filesystem root