Merge pull request #23 from Daylily-Informatics/ops/nuke-rebuild-dev-20260125-030810

Ops/nuke rebuild dev 20260125 030810

Author: iamh2o

.augment/rules/default.md

@@ -0,0 +1,44 @@
+# Marvain — repo-local Augment rules (default)
+
+These rules are **repo-specific** and layer on top of the global rules in `~/.augment/rules/00_base_rules.md`.
+
+## Environment
+- Primary environment manager is **Conda**.
+  - Env name: `marvain`
+  - Spec file: `config/marvain_conda.yaml`
+  - Python: **3.11**
+- Prefer activating with:
+  - `. ./marvain_activate`
+- Treat `MARVAIN_ALLOW_VENV=1` as an escape hatch only (use only if explicitly requested).
+
+## Safety (AWS / destructive operations)
+- Do **not** run destructive or stateful AWS operations without explicit Major approval.
+  - Examples: `sam deploy`, CloudFormation updates/deletes, S3 deletes, DB init against real stacks.
+- Prefer `--dry-run` modes whenever available (e.g., `./bin/marvain ... --dry-run`).
+
+## Testing & verification (default)
+- Fast local signal:
+  - `python -m pytest -q`
+- When changing CLI behavior, prefer adding/updating tests under `tests/`.
+
+## Codebase conventions
+- Runtime/targets:
+  - AWS SAM/CloudFormation stack in `template.yaml`
+  - Lambda code in `functions/`
+  - Shared library in `layers/shared/`
+  - CLI in `marvain_cli/` and wrapper in `bin/marvain`
+- Prefer **stdlib / existing deps**; adding dependencies requires justification.
+
+## Architecture: GUI vs API
+- **Hub API (deployed)**: REST API Lambda behind API Gateway for programmatic access (devices, CLI, satellites). Uses `api_app.py` via `lambda_handler.py`.
+- **GUI (local only)**: FastAPI app with Jinja2 templates + HTMX, runs on `localhost:8084`. Uses `app.py` which imports `api_app` and adds GUI routes.
+- GUI authenticates via Cognito Hosted UI and connects directly to deployed AWS resources (Aurora Data API, Cognito, S3, SQS).
+- **Never deploy GUI to Lambda** — keep GUI code out of `api_app.py`.
+
+## Logging & determinism
+- Prefer explicit configuration (flags/config) over implicit shell state.
+- When wrapping external tools (AWS/SAM), log the exact command being run (unless quiet mode).
+
+## Documentation updates
+- If behavior changes, update the nearest doc:
+  - `README.md`, `QUICKSTART.md`, and/or `docs/ARCHITECTURE.md`.

AGENTS.md

@@ -0,0 +1,2 @@
+# ALWAYS RUN THIS: source marvain_activate when in the repo root directory and when starting a new terminal so you have the cli tools available. AND try to source .env as well, if present.
+

README.md

@@ -179,6 +179,13 @@ Prereqs:
 
 Notes:
 
+- `./bin/marvain deploy` defaults to **guided** (interactive) SAM deploy.
+- For a fully non-interactive deploy (no stdin prompts), use:
+  - `./bin/marvain deploy --no-guided`
+- `deploy` runs a `sam build --clean` first so Lambda functions include vendored dependencies.
+
+Notes:
+
 - `marvain config init` writes to `${XDG_CONFIG_HOME:-~/.config}/marvain/marvain.yaml` by default.
 - Treat that config as **secret** once you run `marvain bootstrap` (it will store a device token).
 - If you choose to write a repo-local config (e.g. `--write marvain.yaml`), it is gitignored.
@@ -196,13 +203,59 @@ Notes:
 ./bin/marvain bootstrap --dry-run --agent-name Forge --space-name home
 ```
 
-### 5) Open the deployed GUI
+### 5) Start the Local GUI
+
+The GUI runs locally on your machine and connects to deployed AWS resources (Aurora, Cognito, S3).
 
 ```bash
-# Print the deployed GUI URL (HubRestApiBase) and open it in your browser.
+# Write stack outputs to .env.local config
+./bin/marvain monitor outputs --write-config
+
+# Start the local GUI server (background mode, default)
+./bin/marvain gui start
+
+# Or just `marvain gui` (defaults to start)
 ./bin/marvain gui
 ```
 
+Visit `http://localhost:8084/` — you'll be redirected to Cognito for login.
+
+#### GUI Lifecycle Commands
+
+| Command | Description |
+|---------|-------------|
+| `marvain gui start` | Start GUI server (background by default) |
+| `marvain gui stop` | Stop the running GUI server |
+| `marvain gui restart` | Stop then start the GUI server |
+| `marvain gui status` | Show whether GUI is running, PID, port |
+| `marvain gui logs` | Show/tail GUI server logs |
+
+**Options:**
+
+```bash
+# Start in foreground (blocking, Ctrl+C to stop)
+./bin/marvain gui start --foreground
+
+# Use different host/port
+./bin/marvain gui start --host 0.0.0.0 --port 8080
+
+# Disable auto-reload
+./bin/marvain gui start --no-reload
+
+# Force kill (SIGKILL instead of SIGTERM)
+./bin/marvain gui stop --force
+
+# Follow logs in real-time
+./bin/marvain gui logs --follow
+
+# Show last 100 lines of logs
+./bin/marvain gui logs --lines 100
+```
+
+**Files:**
+- PID file: `.marvain-gui.pid` (in repo root)
+- Log file: `.marvain-gui.log` (in repo root)
+
 ## Run the realtime agent worker (local)
 
 This repo does not ship a full satellite app yet; it ships a worker skeleton.

config/marvain_conda.yaml

@@ -10,7 +10,7 @@ dependencies:
 
   # Tooling
   - awscli
-	  - pytest
+  - pytest
   - typer
   - click
   - pyyaml
@@ -30,8 +30,10 @@ dependencies:
 
   # Packages not consistently available via conda (or with extras)
   - pip:
-      # awscli v2 requires awscrt crypto EC support (needs awscrt >= 0.28.4)
-      - "awscrt>=0.28.4"
+      - awscli  # v2 requires awscrt crypto EC support (needs awscrt >= 0.28.4)
+      - awscrt
       - amazon-transcribe
-      - "livekit-agents[openai]~=1.3"
-      - "livekit-plugins-noise-cancellation~=0.2"
+      - livekit-agents[openai]
+      - livekit-plugins-noise-cancellation
+      - python-jose[cryptography]  # JWT validation for Cognito auth
+      - itsdangerous  # Session signing for SessionMiddleware

functions/hub_api/.env.local

@@ -0,0 +1,44 @@
+# Local development environment for Hub API
+# These values point to the deployed AWS resources
+
+# Database (Aurora Serverless v2 with Data API)
+DB_RESOURCE_ARN=arn:aws:rds:us-east-1:670484050738:cluster:marvain-john-major-dev-auroracluster-58dmuasoghuv
+DB_SECRET_ARN=arn:aws:secretsmanager:us-east-1:670484050738:secret:marvain-john-major-dev/db-credentials-zoY5wV
+DB_NAME=agenthub
+
+# Cognito
+COGNITO_REGION=us-east-1
+COGNITO_USER_POOL_ID=us-east-1_vGmWnreMU
+COGNITO_APP_CLIENT_ID=7njmj42lc6p2qf6mgsua05miua
+COGNITO_DOMAIN=marvain-dev.auth.us-east-1.amazoncognito.com
+COGNITO_REDIRECT_URI=http://localhost:8084/auth/callback
+
+# Session (for local dev, use a static key; in Lambda, SESSION_SECRET_ARN is used)
+SESSION_SECRET_KEY=local-dev-session-secret-key-change-in-production-123456
+
+# Secrets Manager
+ADMIN_SECRET_ARN=arn:aws:secretsmanager:us-east-1:670484050738:secret:marvain-john-major-dev/admin-api-key-rRWQF7
+OPENAI_SECRET_ARN=arn:aws:secretsmanager:us-east-1:670484050738:secret:marvain-john-major-dev/openai-JNurv6
+LIVEKIT_SECRET_ARN=arn:aws:secretsmanager:us-east-1:670484050738:secret:marvain-john-major-dev/livekit-3qohPq
+
+# LiveKit
+LIVEKIT_URL=wss://marvain-dev-fo5ki513.livekit.cloud
+
+# SQS Queues (URLs not exported - optional for local dev)
+TRANSCRIPT_QUEUE_URL=
+ACTION_QUEUE_URL=
+
+# S3 Buckets
+AUDIT_BUCKET=marvain-john-major-dev-auditbucket-miz3vbanlu3i
+ARTIFACT_BUCKET=marvain-john-major-dev-artifactbucket-0mjzoilnzult
+
+# Logging
+LOG_LEVEL=DEBUG
+
+# Environment
+ENVIRONMENT=local
+
+# AWS
+AWS_PROFILE=daylily
+AWS_REGION=us-east-1
+