docs: add internal deployment guide, remove temp debug files

- Delete BUG-REPORT.md (bug resolved)
- Delete MonarchAPI.md (research complete, library chosen)
- Add .deployment.md with Komodo stack ops, auth notes, and troubleshooting

.deployment.md

@@ -0,0 +1,207 @@
+# Monarch MCP Custom — Deployment Guide
+
+> **Internal / Private.** Not for public distribution. This doc covers how the local Komodo deployment works and how to operate it.
+
+---
+
+## Architecture
+
+```
+Git push to main
+    |
+    v
+Gitea Actions (.gitea/workflows/build.yaml)
+    |
+    v
+Docker build + push to gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest
+    |
+    v
+Komodo Stack "monarch-mcp" pulls image and deploys
+    |
+    v
+Container runs on host port 8070 (mapped to container 8000)
+```
+
+---
+
+## Gitea Build Workflow
+
+**File:** `.gitea/workflows/build.yaml`
+
+Triggers on every push to `main` or `master`:
+
+1. Checks out the repo
+2. Logs into `gitea.ext.ben.io` container registry (uses `secrets.CR_PAT`)
+3. Builds and pushes `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest`
+
+### Manual Build Trigger
+
+If you need to force a rebuild without a code change, push an empty commit:
+
+```bash
+git commit --allow-empty -m "chore: trigger rebuild"
+git push origin main
+```
+
+Or edit `.gitea/workflows/build.yaml` and push.
+
+---
+
+## Komodo Stack Deployment
+
+**Stack Name:** `monarch-mcp`
+**Server:** `6942f06939bbe4eb5a9f21aa` (main Docker host)
+**Image:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest`
+**Host Port:** `8070` → Container `8000`
+
+### Environment Variables (from `.env`)
+
+| Variable | Purpose | Source |
+|---|---|---|
+| `MONARCH_TOKEN` | Session token for Monarch Money API | Extract from browser DevTools |
+| `MONARCH_EMAIL` | Account email for re-auth fallback | Plaintext |
+| `MONARCH_PASSWORD` | Account password for re-auth fallback | Plaintext |
+| `MONARCH_MFA_SECRET` | TOTP secret for re-auth fallback | Plaintext (from 2FA setup) |
+| `MONARCH_PORT` | Host port mapping (default 8070) | `.env` |
+| `LOG_LEVEL` | Python logging level (INFO/DEBUG) | `.env` |
+
+### How to Redeploy
+
+**Via Komodo UI:**
+1. Navigate to Stacks → monarch-mcp
+2. Click **Deploy** (or **Pull** then **Deploy** to force fresh image)
+
+**Via MCP / API:**
+```python
+# Using the komodo_mcp tool
+DeployStack(stack="monarch-mcp")
+```
+
+**Force fresh image pull:**
+The stack has `auto_pull: true`, so a standard Deploy should pull the latest image. If not, use **Pull Stack** first.
+
+---
+
+## Container Operations
+
+### Check Logs
+
+**Via Komodo UI:**
+Stack → monarch-mcp → Logs → Select service `monarch-mcp`
+
+**Via Komodo API:**
+```python
+GetStackLog(stack="monarch-mcp", services=["monarch-mcp"], tail=50)
+```
+
+### Health Check
+
+The container exposes a health endpoint:
+
+```bash
+curl http://localhost:8070/health
+# Expected: {"status": "ok"}
+```
+
+Docker compose healthcheck config (in `compose.yaml`):
+- Interval: 30s
+- Timeout: 10s
+- Retries: 3
+- Start period: 10s
+
+---
+
+## Local Development
+
+### Install Dependencies
+
+```bash
+uv sync
+```
+
+### Run Locally
+
+```bash
+uv run python src/monarch_mcp_custom/server.py
+# or
+python -m monarch_mcp_custom.server
+```
+
+### Test the Library Directly
+
+```bash
+uv run python -c "
+from monarchmoney import MonarchMoney, MonarchMoneyEndpoints
+print(MonarchMoneyEndpoints.BASE_URL)
+"
+```
+
+---
+
+## Authentication Notes
+
+### Token Source
+The `MONARCH_TOKEN` is a session token extracted from browser DevTools:
+1. Log into Monarch Money at `https://app.monarch.com`
+2. Open DevTools → Network → filter by `graphql`
+3. Click any request → Headers → `Authorization: Token <value>`
+4. Copy the token value (without `Token ` prefix)
+
+### Token Lifetime
+Tokens appear to last several months. If API calls start returning 401:
+1. Extract a fresh token from the browser
+2. Update the `MONARCH_TOKEN` env var in Komodo
+3. Redeploy the stack
+
+### Re-Authentication Fallback
+If token auth fails, the MCP server will attempt to re-authenticate using `MONARCH_EMAIL`, `MONARCH_PASSWORD`, and `MONARCH_MFA_SECRET`. This is subject to rate limiting by Monarch.
+
+---
+
+## Troubleshooting
+
+### 401 Unauthorized
+- Token expired? Extract fresh token from browser.
+- Check `MONARCH_TOKEN` is set correctly in Komodo stack env.
+- Verify library version in startup logs (should show `monarchmoney 1.3.2+` and `BASE_URL: https://api.monarch.com`).
+
+### 429 Rate Limited
+- Monarch Money rate-limits login attempts.
+- Wait ~15-60 seconds before retrying.
+- The retry decorator handles 429 with a 15s backoff.
+
+### Image Not Updating
+- Check Gitea Actions for build failures.
+- Force a **Pull Stack** in Komodo before deploying.
+- Verify the commit hash in Komodo matches the latest.
+
+### Build Fails
+- Check `.gitea/workflows/build.yaml` logs in Gitea.
+- Ensure `secrets.CR_PAT` is valid for `gitea.ext.ben.io`.
+
+---
+
+## Useful Commands
+
+```bash
+# Quick health check
+curl -s http://localhost:8070/health | jq .
+
+# Check running container
+docker ps | grep monarch-mcp
+
+# Inspect container logs directly on host
+docker logs monarch-mcp-custom --tail 50 -f
+
+# Restart container
+docker restart monarch-mcp-custom
+```
+
+---
+
+## Related Resources
+
+- **Repo:** `git.local.ben.io:b3nw/monarch-mcp-custom.git`
+- **Container Registry:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom`
+- **Komodo Stack:** `monarch-mcp` (ID: `694b492b6e2254e6ad636e9b`)
+- **Upstream Library:** https://github.com/bradleyseanf/monarchmoneycommunity