Initial project setupHEADmain

Add modal-shell project with .agent/ config, mode stubs, ms dispatcher,
bare repo at /site/git.terst.org/repos/modal-shell.git, and ADR-001.

1 files changed, 15 insertions, 0 deletions

diff --git a/.agent/narrative.md b/.agent/narrative.md
new file mode 100644
index 0000000..f14998e
--- /dev/null
+++ b/.agent/narrative.md
@@ -0,0 +1,15 @@
+# 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.