Add Vellem agent guidance and demo-prep make targets.

AGENTS.md

@@ -7,6 +7,7 @@ Repo-specific guidance for AI agents and contributors working in `splunk-mcp`.
 - **Purpose**: local PoC that runs **Splunk Enterprise** in Docker and exposes **Splunk MCP Server** on `https://localhost:8089/services/mcp`.
 - **Client bridge**: **Claude Desktop**, **Cursor**, and **Goose** use **`npx mcp-remote`** to `https://localhost:8089/services/mcp` (token minted at `make update-*-config` after **`splunk-init`** completes; stored only in client config, not the repo). See `make update-mcp-clients` or `make update-mcp-client MCP_CLIENT=…`. **SE / presales**: **`docs/PRESALES.md`**.
 - **Sample app**: **`SA-S4R`** (UI label **Splunk4Rookies**) — bind-mounted Eventgen traffic, lookups, dashboard assets. See **`docs/SA-S4R-APP.md`** and **`docs/What Does the Business Want to See.md`** (workshop dashboard spec).
+- **Session memory (Vellem)**: when the **vellem** MCP server is enabled in Cursor, start with **`search_notes_semantic`** on folder **`splunk-mcp`** (boot, verify, troubleshooting) before deep doc reads. Use **`list_expiring_contexts`** to avoid stale notes. After demos or non-obvious fixes, capture outcomes in Vellem (**`add_decision_note`** / **`append_to_daily`**) — not in git. Splunk MCP handles live data; Vellem holds repo-specific memory (no secrets).
 
 ## Golden rules (don’t break these)
 
@@ -51,6 +52,7 @@ Splunk REST bootstrap (see **`docs/SETUP_SPLUNK_SCRIPT.md`** for detail):
 | -------- | ----------------- |
 | Stack healthy? | `make status` — **`splunk-init`** line + **Splunk is ready ✓**; exits non-zero if init failed or Splunk down |
 | MCP client path OK? | `make verify-mcp-remote` (all clients) or `make verify-mcp-remote MCP_VERIFY_CLIENT=cursor` |
+| Pre-demo / both checks? | `make demo-prep` (status + verify + warm-stack reminder) or `make verify` (status then verify only) |
 | Init failed? | `docker logs splunk-init` (see **`docs/TROUBLESHOOTING.md`**) |
 | Eventgen modinput? | `curl -k -u admin:<password> "https://localhost:8089/servicesNS/nobody/SA-Eventgen/data/inputs/modinput_eventgen/default?output_mode=json"` |
 
@@ -73,7 +75,7 @@ Splunk REST bootstrap (see **`docs/SETUP_SPLUNK_SCRIPT.md`** for detail):
 ## Change discipline
 
 - Prefer small commits; keep **`make up`**, **`make status`**, **`make verify-mcp-remote`** working.
-- When changing **`Makefile`**, **`compose.yml`**, or **`scripts/setup-splunk.sh`**, update **`docs/CONFIGURATION.md`**, **`docs/OVERVIEW.md`**, and/or **`docs/TROUBLESHOOTING.md`** as needed.
+- When changing **`Makefile`**, **`compose.yml`**, or **`scripts/setup-splunk.sh`**, update **`docs/CONFIGURATION.md`**, **`docs/OVERVIEW.md`**, and/or **`docs/TROUBLESHOOTING.md`** as needed; refresh or expire Vellem **`splunk-mcp`** folder notes when behavior changes.
 - Lint before push: **`pre-commit run --all-files`** (**shellcheck** on **`scripts/*.sh`**, **markdownlint-cli2** on Markdown). Requires **shellcheck** on PATH (`brew install shellcheck`) and **Node/npx**. Auto-fix Markdown: `npx --yes markdownlint-cli2 --fix`.
 - **License:** contributions are under **[LICENSE](LICENSE)** (MIT).
 

Makefile

@@ -14,7 +14,7 @@ MCP_CLIENTS := cursor goose claude
 
 export ENV_FILE ENV_OUT ENV_EXAMPLE OP DC
 
-.PHONY: help up down restart clean logs status \
+.PHONY: help up down restart clean logs status demo-prep verify \
 	update-mcp-clients update-mcp-client verify-mcp-remote \
 	update-claude-config update-cursor-config update-goose-config
 
@@ -88,3 +88,18 @@ update-goose-config: ## Goose: npx mcp-remote + bearer token
 
 verify-mcp-remote: ## Verify client configs + Splunk MCP (MCP_VERIFY_CLIENT=all|…)
 	@./scripts/mcp-client.sh verify "$(MCP_VERIFY_CLIENT)"
+
+demo-prep: ## Pre-demo check: status + MCP verify + warm-stack reminder
+	@echo "=== Splunk MCP demo prep ==="
+	@echo "Tip: warm the stack before a live meeting — cold 'make up' can take many minutes."
+	@echo ""
+	@$(MAKE) status
+	@echo ""
+	@$(MAKE) verify-mcp-remote
+	@echo ""
+	@echo "Demo prep complete. Restart Cursor/Claude if you refreshed MCP configs."
+	@echo "Splunk Web: https://localhost:8000 | MCP: https://localhost:8089/services/mcp"
+
+verify: ## Stack status then Splunk MCP client verify
+	@$(MAKE) status
+	@$(MAKE) verify-mcp-remote

docs/INSTALLATION.md

@@ -142,7 +142,7 @@ Use **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** for Docker, ports, `op` auth, S
 
 ## Security (local PoC)
 
-This setup targets **trusted localhost** use: self-signed TLS, dev-oriented MCP settings. Do not treat it as production-ready. See [SECURITY.md](SECURITY.md). Do not commit **`.env`**, **`.secrets/`**, or client files containing live tokens.
+This setup targets **trusted localhost** use: self-signed TLS, dev-oriented MCP settings. Do not treat it as production-ready. See [SECURITY.md](SECURITY.md). Do not commit **`.env`**, **`tpl.env`**, or client files containing live MCP bearer tokens. (Legacy **`.secrets/`** is gitignored and only used when **`ALLOW_LEGACY_SECRETS=1`** — tokens are not written there.)
 
 ## Next steps
 

docs/PRESALES.md

@@ -14,9 +14,9 @@ This repo is a **local proof-of-concept**: **Splunk Enterprise** in Docker, **Sp
    - **Path B (no 1Password):** `cp .env.example .env`, fill `SPLUNK_PASSWORD`, `SPLUNKBASE_USER`, `SPLUNKBASE_PASS`, `SPLUNK_MCP_PASSWORD`, `SPLUNK_IMAGE`, `TZ`. Never commit `.env`.
 3. **Network:** The host must reach **splunkbase.splunk.com** (HTTPS) and your container registry (e.g. Docker Hub). VPN/firewall/proxy often blocks corporate demos—test ahead.
 4. **Start:** `make up` from the repo root. First cold start is often **several minutes** (image pull, Splunk, Splunkbase app downloads, **`splunk-init`**). For a live meeting, warm the stack **before** the call or the day before.
-5. **Wait for green:** `make status` until it prints **Splunk is ready ✓**.
+5. **Wait for green:** `make status` until it prints **Splunk is ready ✓** (or run **`make demo-prep`** — status + MCP verify + warm-stack reminder).
 6. **Cursor (recommended):** **`make up`** already wrote **`.cursor/mcp.json`**; restart Cursor or reload MCP servers. Confirm Splunk/MCP tools in the tool list and run a **read-only** tool (e.g. a small search).
-7. **Sanity check from the shell:** `make verify-mcp-remote` (checks all client configs + Splunk MCP `tools/list`).
+7. **Sanity check from the shell:** `make verify-mcp-remote` or **`make demo-prep`** (checks all client configs + Splunk MCP `tools/list`).
 8. **Claude / Goose (if used):** **`make up`** runs **`update-mcp-clients`**; **quit Claude fully (Cmd+Q)** and reopen, and restart Goose.
 
 If anything fails, go straight to [TROUBLESHOOTING.md](TROUBLESHOOTING.md) (Splunkbase auth, ports, token timeout, MCP 401).

docs/QUICK_START.md

@@ -33,8 +33,9 @@ With **`tpl.env`** and no **`.env`**, **`make up`** injects secrets via **`op ru
 ## 3. Verify
 
 ```bash
-make status
-make verify-mcp-remote
+make demo-prep    # status + MCP verify + presales reminder
+# or:
+make verify       # status then verify-mcp-remote only
 ```
 
 - Splunk Web: `https://localhost:8000` (admin + password from your secret source).