1 files changed, 88 insertions, 0 deletions
diff --git a/.agent/config.md b/.agent/config.md
new file mode 100644
index 0000000..af6c1fd
--- /dev/null
+++ b/.agent/config.md
@@ -0,0 +1,88 @@
+# Agent Config — modal-shell
+*Main entry point. Read this first, every session.*
+
+## Quick Links
+
+| File | Purpose |
+|---|---|
+| `worklog.md` | Session state: current focus, recently completed, next steps |
+| `design.md` | Architecture overview and component map |
+| `coding_standards.md` | Shell scripting conventions and testing |
+| `mission.md` | Project goals and agent role |
+| `narrative.md` | Background and history |
+| `preferences.md` | User-specific preferences |
+| `docs/adr/` | Architectural decision records |
+
+---
+
+## Core Mandates
+
+### Safety Protocol
+
+1. **Inquiry-Only Default** — Treat every message as research or analysis unless it is an explicit, imperative instruction.
+2. **Zero Unsolicited Changes** — Never modify files or scripts based on assumptions about intent.
+3. **Strategy Checkpoint** — Research first. Present approach. Wait for explicit approval before touching anything outside `.agent/`.
+4. **Verify State First** — Check current state (`ls`, `git status`, `cat` the relevant file) before proposing changes.
+5. **Destructive Operations Require Confirmation** — Any change that deletes, overwrites, or resets state must be confirmed explicitly.
+
+### Living Documentation
+
+1. **Update `.agent/` continuously** — When decisions are made, patterns emerge, or preferences are revealed, update the relevant file immediately.
+2. **Worklog at start and end** — `worklog.md` reflects what was done this session and what comes next.
+3. **ADRs for architecture decisions** — Any significant structural or tooling decision gets an entry in `docs/adr/`.
+
+---
+
+## Workflow
+
+```
+Research → Strategy → Execution
+```
+
+1. **Research** — Read the relevant mode files and base.sh. Understand the current pattern before proposing changes.
+2. **Strategy** — Describe the change and why. For anything beyond a trivial edit, wait for a "go ahead."
+3. **Execution**
+   - Make the change.
+   - Verify it works: run `ms <mode>` in a subshell or with `bash -n` for syntax.
+   - Update `worklog.md`.
+
+---
+
+## Project Layout
+
+```
+modal-shell/
+  ms                  # dispatcher (entry point for users)
+  .envrc              # direnv: auto-sources base.sh on cd
+  modes/
+    base.sh           # sourced by all modes; env, secrets, PROJECT_ROOT
+    db.sh             # database shell mode
+    build.sh          # build pipeline mode
+    reset.sh          # destructive rebuild mode (prompts for confirmation)
+    logs.sh           # log streaming mode
+  docs/
+    adr/              # architectural decision records
+  .agent/             # agent configuration (this directory)
+  CLAUDE.md           # repo root entry point
+```
+
+---
+
+## Essential Commands
+
+| Command | Action |
+|---|---|
+| `ms <mode>` | Enter a named mode |
+| `ms` (no args) | List available modes |
+| `bash -n modes/<mode>.sh` | Syntax-check a mode file |
+| `direnv allow` | Trust `.envrc` after changes |
+| `source modes/base.sh` | Manually load base env |
+
+---
+
+## What NOT to Do
+
+- Do not add logic to the `ms` dispatcher beyond finding and executing mode files.
+- Do not store secrets in any file in this repo.
+- Do not create modes that silently do destructive things.
+- Do not introduce dependencies that aren't already in the base environment.