# Narrative

## Origin

modal-shell began as four zsh scripts in a Vagrant-based PHP project circa ~2014. The original `up.zsh` booted a VM and SSH'd in; sibling scripts (`mysql.zsh`, `phing.zsh`) set `VAGRANT_OPTS` before delegating to it. The pattern was right — intent-at-entry-point — but the implementation was buried in a single project and tied entirely to Vagrant and Phing.

## The Insight Worth Keeping

The composition model — "set context, call the base" — is sound. What was wrong was everything specific to the stack: Vagrant, Phing, hardcoded paths, unprotected env vars for secrets, no confirmation on destructive operations.

The modal concept maps cleanly to modern tooling. `vagrant up && vagrant ssh` becomes `docker compose exec` or `nix develop`. `VAGRANT_OPTS` becomes proper mode files with sourced base environments. Phing becomes `just` or `make`.

## Current Phase

Greenfield rewrite. The original repo (`thepeterstone/modal-shell`) is reference only. The new implementation lives at `/workspace/modal-shell` and follows the project conventions established here.