better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/local-ollama-setup.md

@@ -0,0 +1,338 @@
+---
+sidebar_position: 9
+title: "Run Hermes Locally with Ollama — Zero API Cost"
+description: "Step-by-step guide to running Hermes Agent entirely on your own machine with Ollama and open-weight models like Gemma 4, no cloud API keys or paid subscriptions needed"
+---
+
+# Run Hermes Locally with Ollama — Zero API Cost
+
+:::tip Desktop users: there's a one-click path
+On the Hermes desktop app, **Settings → Providers → Local Models** installs
+and manages a local llama.cpp server for you — model downloads, memory
+fitting, and context sizing included. See [Local Models](/user-guide/local-models).
+This guide is for manual setup: Ollama specifically, CLI-first workflows,
+or servers you want to run yourself.
+:::
+
+## The Problem
+
+Cloud LLM APIs charge per token. A heavy coding session can cost $5–20. For personal projects, learning, or privacy-sensitive work, that adds up — and you're sending every conversation to a third party.
+
+## What This Guide Solves
+
+You'll set up Hermes Agent running entirely on your own hardware, using [Ollama](https://ollama.com) as the model backend. No API keys, no subscriptions, no data leaving your machine. Once configured, Hermes works exactly like it does with OpenRouter or Anthropic — terminal commands, file editing, web browsing, delegation — but the model runs locally.
+
+By the end, you'll have:
+
+- Ollama serving one or more open-weight models
+- Hermes connected to Ollama as a custom endpoint
+- A working local agent that can edit files, run commands, and browse the web
+- Optional: a Telegram/Discord bot powered entirely by your own hardware
+
+## What You Need
+
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| **RAM** | 8 GB (for 3B models) | 32+ GB (for 27B+ models) |
+| **Storage** | 5 GB free | 30+ GB (for multiple models) |
+| **CPU** | 4 cores | 8+ cores (AMD EPYC, Ryzen, Intel Xeon) |
+| **GPU** | Not required | NVIDIA GPU with 8+ GB VRAM speeds things up significantly |
+
+:::tip CPU-only works, but expect slower responses
+Ollama runs on CPU-only servers. A 9B model on a modern 8-core CPU gives ~10 tokens/sec. A 31B model on CPU is slower (~2–5 tokens/sec) — each response takes 30–120 seconds, but it works. A GPU dramatically improves this. For CPU-only setups, widen the API timeout via the env var (it's not a `config.yaml` key):
+
+```bash
+# ~/.hermes/.env
+HERMES_API_TIMEOUT=1800   # 30 minutes — generous for slow local models
+```
+:::
+
+## Step 1: Install Ollama
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+Verify it's running:
+
+```bash
+ollama --version
+curl http://localhost:11434/api/tags   # Should return {"models":[]}
+```
+
+## Step 2: Pull a Model
+
+Choose based on your hardware:
+
+| Model | Size on Disk | RAM Needed | Tool Calling | Best For |
+|-------|-------------|------------|:------------:|----------|
+| `gemma4:31b` | ~20 GB | 24+ GB | Yes | Best quality — strong tool use and reasoning |
+| `gemma2:27b` | ~16 GB | 20+ GB | No | Conversational tasks, no tool use |
+| `gemma2:9b` | ~5 GB | 8+ GB | No | Fast chat, Q&A — cannot call tools |
+| `llama3.2:3b` | ~2 GB | 4+ GB | No | Lightweight quick answers only |
+
+:::warning Tool calling matters
+Hermes is an **agentic** assistant — it edits files, runs commands, and browses the web through tool calls. Models without tool-call support can only chat; they can't take actions. For the full Hermes experience, use a model that supports tools (like `gemma4:31b`).
+:::
+
+Pull your chosen model:
+
+```bash
+ollama pull gemma4:31b
+```
+
+:::info Multiple models
+You can pull several models and switch between them inside Hermes with `/model`. Ollama loads the active model into memory on demand and unloads idle ones automatically.
+:::
+
+Verify the model works:
+
+```bash
+curl http://localhost:11434/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gemma4:31b",
+    "messages": [{"role": "user", "content": "Say hello"}],
+    "max_tokens": 50
+  }'
+```
+
+You should see a JSON response with the model's reply.
+
+## Step 3: Configure Hermes
+
+Run the Hermes setup wizard:
+
+```bash
+hermes setup
+```
+
+When prompted for a provider, select **Custom Endpoint** and enter:
+
+- **Base URL:** `http://localhost:11434/v1`
+- **API Key:** Leave empty or type `no-key` (Ollama doesn't need one)
+- **Model:** `gemma4:31b` (or whichever model you pulled)
+
+Alternatively, edit `~/.hermes/config.yaml` directly:
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+```
+
+## Step 4: Start Using Hermes
+
+```bash
+hermes
+```
+
+That's it. You're now running a fully local agent. Try it out:
+
+```
+You: List all Python files in this directory and count the lines of code in each
+
+You: Read the README.md and summarize what this project does
+
+You: Create a Python script that fetches the weather for Ho Chi Minh City
+```
+
+Hermes will use the terminal tool, file operations, and your local model — no cloud calls.
+
+## Step 5: Pick the Right Model for Your Task
+
+Not every task needs the biggest model. Here's a practical guide:
+
+| Task | Recommended Model | Why |
+|------|-------------------|-----|
+| File edits, code, terminal commands | `gemma4:31b` | Only model with reliable tool calling |
+| Quick Q&A (no tool use needed) | `gemma2:9b` | Fast responses for conversational tasks |
+| Lightweight chat | `llama3.2:3b` | Fastest, but very limited capabilities |
+
+:::note
+For full agentic work (editing files, running commands, browsing), `gemma4:31b` is currently the best local option with tool-call support. Check [Ollama's model library](https://ollama.com/library) for newer models — tool-calling support is expanding rapidly.
+:::
+
+Switch models on the fly inside a session:
+
+```
+/model gemma2:9b
+```
+
+## Step 6: Optimize for Speed
+
+### Increase Ollama's Context Window
+
+By default, Ollama uses a 2048-token context. Hermes requires at least 64,000 tokens for agentic work with tools:
+
+```bash
+# Create a Modelfile that extends context
+cat > /tmp/Modelfile << 'EOF'
+FROM gemma4:31b
+PARAMETER num_ctx 64000
+EOF
+
+ollama create gemma4-64k -f /tmp/Modelfile
+```
+
+Then update your Hermes config to use `gemma4-64k` as the model name.
+
+### Keep the Model Loaded
+
+By default, Ollama unloads models after 5 minutes of inactivity. For a persistent gateway bot, keep it loaded:
+
+```bash
+# Set keep-alive to 24 hours
+curl http://localhost:11434/api/generate \
+  -d '{"model": "gemma4:31b", "keep_alive": "24h"}'
+```
+
+Or set it globally in Ollama's environment:
+
+```bash
+# /etc/systemd/system/ollama.service.d/override.conf
+[Service]
+Environment="OLLAMA_KEEP_ALIVE=24h"
+```
+
+### Use GPU Offloading (If Available)
+
+If you have an NVIDIA GPU, Ollama automatically offloads layers to it. Check with:
+
+```bash
+ollama ps   # Shows which model is loaded and how many GPU layers
+```
+
+For a 31B model on a 12 GB GPU, you'll get partial offload (~40 layers on GPU, rest on CPU), which still gives a significant speedup.
+
+## Step 7: Run as a Gateway Bot (Optional)
+
+Once Hermes works locally in the CLI, you can expose it as a Telegram or Discord bot — still running entirely on your hardware.
+
+### Telegram
+
+1. Create a bot via [@BotFather](https://t.me/BotFather) and get the token
+2. Add to your `~/.hermes/config.yaml`:
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+
+platforms:
+  telegram:
+    enabled: true
+    token: "YOUR_TELEGRAM_BOT_TOKEN"
+```
+
+3. Start the gateway:
+
+```bash
+hermes gateway
+```
+
+Now message your bot on Telegram — it responds using your local model.
+
+### Discord
+
+1. Create a Discord application at [discord.com/developers](https://discord.com/developers/applications)
+2. Add to config:
+
+```yaml
+platforms:
+  discord:
+    enabled: true
+    token: "YOUR_DISCORD_BOT_TOKEN"
+```
+
+3. Start: `hermes gateway`
+
+## Step 8: Set Up Fallbacks (Optional)
+
+Local models can struggle with complex tasks. Set up a cloud fallback that only activates when the local model fails:
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+
+fallback_providers:
+  - provider: openrouter
+    model: anthropic/claude-sonnet-4
+```
+
+This way, 90% of your usage is free (local), and only the hard tasks hit the paid API.
+
+## Troubleshooting
+
+### "Connection refused" on startup
+
+Ollama isn't running. Start it:
+
+```bash
+sudo systemctl start ollama
+# or
+ollama serve
+```
+
+### Slow responses
+
+- **Check model size vs RAM:** If your model needs more RAM than available, it swaps to disk. Use a smaller model or add RAM.
+- **Check `ollama ps`:** If no GPU layers are offloaded, responses are CPU-bound. This is normal for CPU-only servers.
+- **Reduce context:** Large conversations slow down inference. Use `/compress` regularly, or set a lower compression threshold in config.
+
+### Slow first response (prefill)
+
+Hermes sends a fixed payload on every API call — the system prompt plus the tool schemas for all enabled tools — before any of your conversation content. On CPU-only or low-VRAM setups, processing that prompt (the *prefill* phase) dominates the first turn: the model can sit silent for minutes while it works through the prompt, then generate at its normal pace. This is expected behaviour, not a hang. The [Mac local-LLM guide](./local-llm-on-mac.md#timeouts) documents the same effect — during prefill on large contexts, local models may produce no output for minutes while processing the prompt — and Hermes automatically raises its stream read timeout from 120s to 1800s for local endpoints (`HERMES_STREAM_READ_TIMEOUT`).
+
+What helps:
+
+- **Keep the model loaded** — Ollama unloads idle models after 5 minutes, adding a full reload before the next prefill. Set `OLLAMA_KEEP_ALIVE=24h` (see [Step 6](#keep-the-model-loaded)).
+- **Widen the API timeout** — set `HERMES_API_TIMEOUT=1800` in `~/.hermes/.env` (see [What You Need](#what-you-need)).
+- **Measure and trim the fixed prompt** — run `hermes prompt-size` for a byte breakdown of the system prompt and tool schemas, then disable unused toolsets with `hermes tools` and uninstall skills you don't need with `hermes skills`.
+- **Use GPU offloading** — even a partial offload gives a significant speedup (see [Step 6](#use-gpu-offloading-if-available)).
+
+### Model doesn't follow tool calls
+
+Models without tool-call support produce plain text instead of structured function calls. Solutions:
+
+- **Use a model with tool-call support** — of the models listed above, only `gemma4:31b` has reliable tool calling.
+- **Hermes has auto-repair** — it detects malformed tool calls and attempts to fix them automatically.
+- **Set up a fallback** — if the local model fails 3 times, Hermes falls back to a cloud provider.
+
+If the model prints raw JSON like `{"name": "web_search", ...}` in its reply instead of actually running the tool, that's usually the *server*, not the model — tool calling isn't enabled or the tool-call format isn't parsed. See the per-server fix table in [Tool calls appear as text instead of executing](/integrations/providers#tool-calls-appear-as-text-instead-of-executing) (llama.cpp needs `--jinja`, vLLM needs `--enable-auto-tool-choice --tool-call-parser hermes`, and so on).
+
+### Context window errors
+
+The default Ollama context (2048 tokens) is too small for agentic work. See [Step 6](#step-6-optimize-for-speed) to increase it.
+
+## Cost Comparison
+
+Here's what running locally saves compared to cloud APIs, based on a typical coding session (~100K tokens input, ~20K tokens output):
+
+| Provider | Cost per Session | Monthly (daily use) |
+|----------|-----------------|---------------------|
+| Anthropic Claude Sonnet | ~$0.80 | ~$24 |
+| OpenRouter (GPT-4o) | ~$0.60 | ~$18 |
+| **Ollama (local)** | **$0.00** | **$0.00** |
+
+Your only cost is electricity — roughly $0.01–0.05 per session depending on hardware.
+
+## What Works Well Locally
+
+- **File editing and code generation** — models 9B+ handle this well
+- **Terminal commands** — Hermes wraps the command, runs it, reads output regardless of model
+- **Web browsing** — the browser tool does the fetching; the model just interprets results
+- **Cron jobs and scheduled tasks** — work identically to cloud setups
+- **Multi-platform gateway** — Telegram, Discord, Slack all work with local models
+
+## What's Better with Cloud Models
+
+- **Very complex multi-step reasoning** — 70B+ or cloud models like Claude Opus are noticeably better
+- **Long context windows** — cloud models offer 100K–1M tokens; local runtimes often default below Hermes' 64K minimum unless you configure them
+- **Speed on large responses** — cloud inference is faster than CPU-only local for long generations
+
+The sweet spot: use local for everyday tasks, set up a cloud fallback for the hard stuff.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/manage-hermes-cloud-with-mcp.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 16
+title: "Manage Hermes Cloud with MCP"
+description: "Connect Hermes Agent to the Nous Portal MCP server so your local agent can list, start, stop, and manage your Hermes Cloud instances conversationally"
+---
+
+# Manage Hermes Cloud with MCP
+
+[Hermes Cloud](https://portal.nousresearch.com/cloud) runs hosted Hermes Agent instances for you. Normally you manage them from the `/agents` page in the [Nous Portal](/integrations/nous-portal). This guide connects your **local** Hermes Agent to the Portal's MCP server so you can manage those cloud instances by just asking — "list my cloud agents", "restart the stopped one", "what's it costing me" — without leaving your terminal.
+
+It's a standard [MCP](/user-guide/features/mcp) server hosted by Nous Research, gated by the same OAuth login you already use for the Portal. Once connected, Hermes gets two tools it can call on your behalf.
+
+## What you can do with it
+
+Once connected, the model can call these on your Hermes Cloud org:
+
+| Ask for… | Under the hood |
+|----------|----------------|
+| "List my cloud agents" | `agents` (list) |
+| "What's the status of `<name>`?" | `agents` (get / status) |
+| "Roughly what is this instance costing?" | `agents` (cost_estimate) |
+| "Start / stop / restart `<name>`" | `agent` (start / stop / restart) |
+| "Spin up a new instance called `<name>`" | `agent` (create) |
+| "Destroy `<name>`" | `agent` (destroy) |
+| "Update the env / image on `<name>`" | `agent` (update_env / update_image) |
+
+Every call runs against **your** org with your Portal identity, and membership is re-checked on each call — the connection can only touch instances you already control from the web UI.
+
+## Prerequisites
+
+- A [Nous Portal](/integrations/nous-portal) account with [Hermes Cloud](https://portal.nousresearch.com/cloud) access (at least one instance, or the ability to create one).
+- MCP support installed. If you used the standard install script it's already there; otherwise:
+
+  ```bash
+  cd ~/.hermes/hermes-agent
+  uv pip install -e ".[mcp]"
+  ```
+
+You do **not** need a separate API key or client secret — the server uses OAuth with PKCE, and the login is a browser round-trip.
+
+## Step 1: add the server
+
+```bash
+hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud
+```
+
+`--auth oauth` tells Hermes this is an OAuth-protected HTTP server. On first connect Hermes:
+
+1. Discovers the server's OAuth endpoints automatically (RFC 9728 / 8414 metadata).
+2. Registers itself as a client (RFC 7591 Dynamic Client Registration) — no secret to copy.
+3. Opens your browser to the Portal to sign in and authorize.
+4. Stores the resulting token under `~/.hermes/mcp-tokens/` and reuses it (refresh is automatic).
+
+### Choosing an organization
+
+If your Portal account belongs to **more than one organization**, the browser shows an **org picker** during authorization — pick which org this connection should manage. The choice is made once, in the browser; there's nothing to pass on the command line. Single-org accounts skip this step and bind automatically.
+
+If you ever need to point the connection at a different org, remove and re-add the server (`hermes mcp remove hermes-cloud`, then the `add` command again) and pick the other org in the browser.
+
+## Step 2: verify it connected
+
+```bash
+hermes mcp test hermes-cloud
+```
+
+Then start (or reload) a session:
+
+```bash
+hermes chat
+```
+
+```text
+/reload-mcp
+```
+
+Ask a read-only question to confirm the tools are live:
+
+```text
+List my Hermes Cloud agents and their current status.
+```
+
+You should get back the same instances you see on the Portal's `/agents` page.
+
+## Step 3: use it
+
+Read-only questions are always safe:
+
+```text
+Which of my cloud agents is currently running, and roughly what is each one costing?
+```
+
+Lifecycle actions map to plain requests:
+
+```text
+Restart the instance called research-bot.
+```
+
+```text
+Create a new Hermes Cloud instance named scratch, then tell me when it's ready.
+```
+
+Hermes reports what each tool returned — the instance list, the new status, the created instance's details — so you can confirm the action landed.
+
+## Configuration
+
+After `hermes mcp add`, the server lives in `~/.hermes/config.yaml`:
+
+```yaml
+mcp_servers:
+  hermes-cloud:
+    url: "https://portal.nousresearch.com/mcp"
+    auth: oauth
+```
+
+No credentials go in `config.yaml` — the OAuth token is kept separately under `~/.hermes/mcp-tokens/`, the same way the Portal refresh token stays out of your config.
+
+### Limiting the tool surface
+
+The server exposes both read (`agents`) and mutating (`agent`) tools. If you want the connection to be **read-only** — list and inspect, but never start/stop/create/destroy — restrict it to the `agents` tool:
+
+```yaml
+mcp_servers:
+  hermes-cloud:
+    url: "https://portal.nousresearch.com/mcp"
+    auth: oauth
+    tools:
+      include: [agents]
+```
+
+Run `/reload-mcp` after changing the config. See [Use MCP with Hermes](/guides/use-mcp-with-hermes) for the full filtering model (`include`/`exclude`, `prompts`, `resources`).
+
+## Troubleshooting
+
+### The browser shows an org picker and I'm not sure which to choose
+
+You belong to multiple Portal organizations. Pick the org whose Hermes Cloud instances you want to manage from this connection. If you're unsure, it's the org that owns the instances you see on the Portal `/agents` page. You can re-choose later by removing and re-adding the server.
+
+### "invalid_client" or "unknown client" on connect
+
+The stored client registration no longer matches the server (for example, you connected to a different environment previously). Clear this server's cached OAuth state and re-add it:
+
+```bash
+hermes mcp remove hermes-cloud
+rm -f ~/.hermes/mcp-tokens/hermes-cloud.*
+hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud
+```
+
+### The tools aren't showing up after adding the server
+
+Reload MCP inside the session and re-check:
+
+```text
+/reload-mcp
+```
+
+```text
+Tell me which MCP-backed tools are available right now.
+```
+
+If they're still missing, run `hermes mcp test hermes-cloud` to see the connection error directly.
+
+### It asks me to log in again
+
+OAuth tokens refresh automatically, but if the Portal invalidates your session (password change, revoke, expiry) the next call asks you to re-authorize. Re-run the `hermes mcp add` command — the browser flow re-mints a token.
+
+### Headless / SSH / remote host
+
+The OAuth browser callback runs on the machine where Hermes is running. On a remote host, forward the loopback port over SSH — the same pattern as any other OAuth login. See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh).
+
+## See also
+
+- **[Nous Portal](/integrations/nous-portal)** — the subscription, models, and Tool Gateway behind the same login
+- **[Use MCP with Hermes](/guides/use-mcp-with-hermes)** — connecting and filtering MCP servers in general
+- **[MCP feature overview](/user-guide/features/mcp)** — what MCP is and how Hermes uses it
+- **[MCP configuration reference](/reference/mcp-config-reference)** — every `mcp_servers` field, including `auth: oauth`
+- **[OAuth over SSH](/guides/oauth-over-ssh)** — logging in from remote or browser-only environments

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/microsoft-graph-app-registration.md

@@ -0,0 +1,180 @@
+---
+title: "Register a Microsoft Graph Application"
+description: "Azure portal walkthrough for creating the app registration that powers the Teams meeting pipeline"
+---
+
+# Register a Microsoft Graph Application
+
+The Teams meeting pipeline reads meeting transcripts, recordings, and related artifacts from Microsoft Graph using **app-only** (daemon) authentication — no user sign-in, no interactive consent per meeting. That requires an Azure AD application registration with admin-consented application permissions.
+
+This guide walks through:
+
+1. Creating the app registration
+2. Creating a client secret
+3. Granting the Graph API permissions the pipeline needs
+4. Admin-consenting those permissions
+5. (Optional) Scoping the app to specific users with an Application Access Policy
+
+You need **tenant admin rights** (or an admin to grant consent on your behalf) to finish this. Bookmark the values you collect — they go into `~/.hermes/.env` at the end.
+
+## Prerequisites
+
+- A Microsoft 365 tenant with Teams Premium or Teams licenses that produce meeting transcripts and recordings
+- Admin access to the Azure portal at [entra.microsoft.com](https://entra.microsoft.com)
+- A publicly reachable HTTPS endpoint for Graph change notifications (set up later, in the webhook listener step)
+
+## Step 1: Create the App Registration
+
+1. Sign in to [entra.microsoft.com](https://entra.microsoft.com) as a tenant admin.
+2. Navigate to **Identity → Applications → App registrations**.
+3. Click **New registration**.
+4. Fill in:
+   - **Name:** `Hermes Teams Meeting Pipeline` (or any name you'll recognize).
+   - **Supported account types:** *Accounts in this organizational directory only (Single tenant)*.
+   - **Redirect URI:** leave blank — app-only auth does not need one.
+5. Click **Register**.
+
+You'll land on the app's overview page. Copy two values:
+
+- **Application (client) ID** → `MSGRAPH_CLIENT_ID`
+- **Directory (tenant) ID** → `MSGRAPH_TENANT_ID`
+
+## Step 2: Create a Client Secret
+
+1. In the left nav, open **Certificates & secrets**.
+2. Click **New client secret**.
+3. **Description:** `hermes-graph-secret`. **Expires:** pick a value that matches your rotation policy (6-24 months is typical).
+4. Click **Add**.
+5. Copy the **Value** column immediately — it's only shown once. That value is `MSGRAPH_CLIENT_SECRET`.
+
+> The **Secret ID** column is not the secret. You want the **Value** column.
+
+## Step 3: Grant Graph API Permissions
+
+The pipeline uses a minimum-viable set of application permissions. Add only what you need; each one widens what the app can read tenant-wide.
+
+1. In the left nav, open **API permissions**.
+2. Click **Add a permission** → **Microsoft Graph** → **Application permissions**.
+3. Add the permissions from the table below that match what you want the pipeline to do.
+4. After adding, click **Grant admin consent for `<your tenant>`**. The Status column should flip to a green checkmark for every permission.
+
+### Required for transcript-first summaries
+
+| Permission | What it lets the app do |
+|------------|--------------------------|
+| `OnlineMeetings.Read.All` | Read Teams online meeting metadata (subject, participants, join URL). |
+| `OnlineMeetingTranscript.Read.All` | Read meeting transcripts generated by Teams. |
+
+### Required for recording fallback (when a transcript is unavailable)
+
+| Permission | What it lets the app do |
+|------------|--------------------------|
+| `OnlineMeetingRecording.Read.All` | Download Teams meeting recordings for offline STT processing. |
+| `CallRecords.Read.All` | Resolve meetings from call records when only the join URL is known. |
+
+### Required for outbound summary delivery (Graph mode only)
+
+If `platforms.teams.extra.delivery_mode` is `graph`, the pipeline posts summaries into a Teams channel or chat via the Graph API. Skip these if you use `incoming_webhook` delivery mode instead.
+
+| Permission | What it lets the app do |
+|------------|--------------------------|
+| `ChannelMessage.Send` | Post messages into Teams channels on behalf of the app. |
+| `Chat.ReadWrite.All` | Post messages into 1:1 and group chats (only if you set `chat_id` as the delivery target). |
+
+### Not recommended
+
+- `OnlineMeetings.ReadWrite.All` / `Chat.ReadWrite` without `.All` — broader than the pipeline needs.
+- Delegated permissions — the pipeline uses app-only (client-credentials) flow; delegated permissions won't work without user sign-in.
+
+## Step 4: (Recommended) Scope the App with an Application Access Policy
+
+By default, application permissions like `OnlineMeetings.Read.All` grant the app access to **every** meeting in the tenant. For partner demos and dev tenants that's fine; for production you almost certainly want to restrict which users' meetings the app can read.
+
+Microsoft provides **Application Access Policies** for Teams exactly for this. The policy is a PowerShell-only surface; there's no portal UI for it.
+
+From an admin PowerShell with the MicrosoftTeams module installed and connected (`Connect-MicrosoftTeams`):
+
+```powershell
+# Create a policy scoped to the Hermes app
+New-CsApplicationAccessPolicy `
+  -Identity "Hermes-Meeting-Pipeline-Policy" `
+  -AppIds "<MSGRAPH_CLIENT_ID>" `
+  -Description "Restrict Hermes meeting pipeline to allow-listed users"
+
+# Grant the policy to specific users whose meetings the pipeline may read
+Grant-CsApplicationAccessPolicy `
+  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
+  -Identity "alice@example.com"
+
+Grant-CsApplicationAccessPolicy `
+  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
+  -Identity "bob@example.com"
+```
+
+Propagation can take up to 30 minutes after granting. Verify with:
+
+```powershell
+Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"
+```
+
+Without the policy, **any** user's meetings are readable — that's what the permission technically grants. Don't skip this step on a production tenant.
+
+## Step 5: Write the Credentials to Your Env File
+
+Put the three values you collected into `~/.hermes/.env`:
+
+```bash
+MSGRAPH_TENANT_ID=<directory-tenant-id>
+MSGRAPH_CLIENT_ID=<application-client-id>
+MSGRAPH_CLIENT_SECRET=<client-secret-value>
+```
+
+Set file permissions so only you can read the secret:
+
+```bash
+chmod 600 ~/.hermes/.env
+```
+
+## Step 6: Verify the Token Flow
+
+Hermes ships a Graph auth smoke-test. From your Hermes install:
+
+```python
+python -c "
+import asyncio
+from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
+provider = MicrosoftGraphTokenProvider.from_env()
+token = asyncio.run(provider.get_access_token())
+print('Token acquired, length:', len(token))
+print(provider.inspect_token_health())
+"
+```
+
+A successful run prints a long token string and a health dict showing `cached: True` and an `expires_in_seconds` value near 3600. Failures produce a `MicrosoftGraphTokenError` with the Azure error code — the most common are:
+
+| Azure error | Meaning | Fix |
+|-------------|---------|-----|
+| `AADSTS7000215: Invalid client secret` | Secret value mismatched or expired. | Generate a new secret in step 2; update `.env`. |
+| `AADSTS700016: Application not found` | Wrong `MSGRAPH_CLIENT_ID` or wrong tenant. | Double-check the values from step 1 are from the same app. |
+| `AADSTS90002: Tenant not found` | Typo in `MSGRAPH_TENANT_ID`. | Copy the Directory (tenant) ID from the app overview again. |
+| `insufficient_claims` at call time (not token time) | Token acquires but Graph returns 401/403. | You skipped step 3 admin-consent, or added permissions but haven't re-consented. Revisit API permissions and click **Grant admin consent** again. |
+
+## Rotating the Client Secret
+
+Azure client secrets have a hard expiry. Before yours expires:
+
+1. Create a second client secret in step 2 without deleting the first one.
+2. Update `MSGRAPH_CLIENT_SECRET` in `~/.hermes/.env` with the new value.
+3. Restart the gateway so the new secret is picked up: `hermes gateway restart`.
+4. Verify with the smoke test above.
+5. Delete the old secret from the Azure portal.
+
+## Next Steps
+
+Once credentials verify cleanly, continue with:
+
+- **Webhook listener setup** — stand up the `msgraph_webhook` gateway platform that receives Graph change notifications.
+- **Pipeline configuration** — configure the Teams meeting pipeline runtime and operator CLI.
+- **Outbound delivery** — wire summaries back into a Teams channel or chat.
+
+Those pages land alongside the PRs that add the corresponding runtime. This credentials setup is a standalone prerequisite and is safe to complete in advance.