better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/daily-briefing-bot.md

@@ -0,0 +1,272 @@
+---
+sidebar_position: 3
+title: "Tutorial: Daily Briefing Bot"
+description: "Build an automated daily briefing bot that researches topics, summarizes findings, and delivers them to Telegram or Discord every morning"
+---
+
+# Tutorial: Build a Daily Briefing Bot
+
+In this tutorial, you'll build a personal briefing bot that wakes up every morning, researches topics you care about, summarizes the findings, and delivers a concise briefing straight to your Telegram or Discord.
+
+By the end, you'll have a fully automated workflow combining **web search**, **cron scheduling**, **delegation**, and **messaging delivery** — no code required.
+
+:::tip
+This recipe hits web search, summarization, and optional TTS — all bundled in a Portal subscription. The fastest setup is `hermes setup --portal`. See [Nous Portal](/integrations/nous-portal).
+:::
+
+## What We're Building
+
+Here's the flow:
+
+1. **8:00 AM** — The cron scheduler triggers your job
+2. **Hermes spins up** a fresh agent session with your prompt
+3. **Web search** pulls the latest news on your topics
+4. **Summarization** distills it into a clean briefing format
+5. **Delivery** sends the briefing to your Telegram or Discord
+
+The whole thing runs hands-free. You just read your briefing with your morning coffee.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **Hermes Agent installed** — see the [Installation guide](/getting-started/installation)
+- **Gateway running** — the gateway daemon handles cron execution:
+  ```bash
+  hermes gateway install   # Install as a user service
+  sudo hermes gateway install --system   # Linux servers: boot-time system service
+  # or
+  hermes gateway           # Run in foreground
+  ```
+- **Firecrawl API key** — set `FIRECRAWL_API_KEY` in your environment for web search
+- **Messaging configured** (optional but recommended) — [Telegram](/user-guide/messaging/telegram) or Discord set up with a home channel
+
+:::tip No messaging? No problem
+You can still follow this tutorial using `deliver: "local"`. Briefings will be saved to `~/.hermes/cron/output/` and you can read them anytime.
+:::
+
+## Step 1: Test the Workflow Manually
+
+Before automating anything, let's make sure the briefing works. Start a chat session:
+
+```bash
+hermes
+```
+
+Then enter this prompt:
+
+```
+Search for the latest news about AI agents and open source LLMs.
+Summarize the top 3 stories in a concise briefing format with links.
+```
+
+Hermes will search the web, read through results, and produce something like:
+
+```
+☀️ Your AI Briefing — March 8, 2026
+
+1. Qwen 3 Released with 235B Parameters
+   Alibaba's latest open-weight model matches GPT-4.5 on several
+   benchmarks while remaining fully open source.
+   → https://qwenlm.github.io/blog/qwen3/
+
+2. LangChain Launches Agent Protocol Standard
+   A new open standard for agent-to-agent communication gains
+   adoption from 15 major frameworks in its first week.
+   → https://blog.langchain.dev/agent-protocol/
+
+3. EU AI Act Enforcement Begins for General-Purpose Models
+   The first compliance deadlines hit, with open source models
+   receiving exemptions under the 10M parameter threshold.
+   → https://artificialintelligenceact.eu/updates/
+
+---
+3 stories • Sources searched: 8 • Generated by Hermes Agent
+```
+
+If this works, you're ready to automate it.
+
+:::tip Iterate on the format
+Try different prompts until you get output you love. Add instructions like "use emoji headers" or "keep each summary under 2 sentences." Whatever you settle on goes into the cron job.
+:::
+
+## Step 2: Create the Cron Job
+
+Now let's schedule this to run automatically every morning. You can do this in two ways.
+
+Before creating cron jobs, ensure Hermes has a default model and provider configured globally. If you want a specific job to use different values, set explicit per-job model/provider overrides when creating it.
+
+### Option A: Natural Language (in chat)
+
+Just tell Hermes what you want:
+
+```
+Every morning at 8am, search the web for the latest news about AI agents
+and open source LLMs. Summarize the top 3 stories in a concise briefing
+with links. Use a friendly, professional tone. Deliver to telegram.
+```
+
+Hermes will create the cron job for you using the unified `cronjob` tool.
+
+### Option B: CLI Slash Command
+
+Use the `/cron` command for more control:
+
+```
+/cron add "0 8 * * *" "Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points and end with a total story count."
+```
+
+### The Golden Rule: Self-Contained Prompts
+
+:::warning Critical concept
+Cron jobs run in a **completely fresh session** — no memory of your previous conversations, no context about what you "set up earlier." Your prompt must contain **everything** the agent needs to do the job.
+:::
+
+**Bad prompt:**
+```
+Do my usual morning briefing.
+```
+
+**Good prompt:**
+```
+Search the web for the latest news about AI agents and open source LLMs.
+Find at least 5 recent articles from the past 24 hours. Summarize the
+top 3 most important stories in a concise daily briefing format. For each
+story include: a clear headline, a 2-sentence summary, and the source URL.
+Use a friendly, professional tone. Format with emoji bullet points.
+```
+
+The good prompt is specific about **what to search**, **how many articles**, **what format**, and **what tone**. It's everything the agent needs in one shot.
+
+## Step 3: Customize the Briefing
+
+Once the basic briefing works, you can get creative.
+
+### Multi-Topic Briefings
+
+Cover several areas in one briefing:
+
+```
+/cron add "0 8 * * *" "Create a morning briefing covering three topics. For each topic, search the web for recent news from the past 24 hours and summarize the top 2 stories with links.
+
+Topics:
+1. AI and machine learning — focus on open source models and agent frameworks
+2. Cryptocurrency — focus on Bitcoin, Ethereum, and regulatory news
+3. Space exploration — focus on SpaceX, NASA, and commercial space
+
+Format as a clean briefing with section headers and emoji. End with today's date and a motivational quote."
+```
+
+### Using Delegation for Parallel Research
+
+For faster briefings, tell Hermes to delegate each topic to a sub-agent:
+
+```
+/cron add "0 8 * * *" "Create a morning briefing by delegating research to sub-agents. Delegate three parallel tasks:
+
+1. Delegate: Search for the top 2 AI/ML news stories from the past 24 hours with links
+2. Delegate: Search for the top 2 cryptocurrency news stories from the past 24 hours with links
+3. Delegate: Search for the top 2 space exploration news stories from the past 24 hours with links
+
+Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."
+```
+
+Each sub-agent searches independently and in parallel, then the main agent combines everything into one polished briefing. See the [Delegation docs](/user-guide/features/delegation) for more on how this works.
+
+### Weekday-Only Schedule
+
+Don't need briefings on weekends? Use a cron expression that targets Monday–Friday:
+
+```
+/cron add "0 8 * * 1-5" "Search for the latest AI and tech news..."
+```
+
+### Twice-Daily Briefings
+
+Get a morning overview and an evening recap:
+
+```
+/cron add "0 8 * * *" "Morning briefing: search for AI news from the past 12 hours..."
+/cron add "0 18 * * *" "Evening recap: search for AI news from the past 12 hours..."
+```
+
+### Adding Personal Context with Memory
+
+If you have [memory](/user-guide/features/memory) enabled, you can store preferences that persist across sessions. But remember — cron jobs run in fresh sessions without conversational memory. To add personal context, bake it directly into the prompt:
+
+```
+/cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.
+
+Search for the latest news on these topics. Summarize the top 3 stories with links. Be concise and technical — this reader doesn't need basic explanations."
+```
+
+:::tip Tailor the persona
+Including details about who the briefing is *for* dramatically improves relevance. Tell the agent your role, interests, and what to skip.
+:::
+
+## Step 4: Manage Your Jobs
+
+### List All Scheduled Jobs
+
+In chat:
+```
+/cron list
+```
+
+Or from the terminal:
+```bash
+hermes cron list
+```
+
+You'll see output like:
+
+```
+ID          | Name              | Schedule    | Next Run           | Deliver
+------------|-------------------|-------------|--------------------|--------
+a1b2c3d4    | Morning Briefing  | 0 8 * * *   | 2026-03-09 08:00   | telegram
+e5f6g7h8    | Evening Recap     | 0 18 * * *  | 2026-03-08 18:00   | telegram
+```
+
+### Remove a Job
+
+In chat:
+```
+/cron remove a1b2c3d4
+```
+
+Or ask conversationally:
+```
+Remove my morning briefing cron job.
+```
+
+Hermes will use `cronjob(action="list")` to find it and `cronjob(action="remove")` to delete it.
+
+### Check Gateway Status
+
+Make sure the scheduler is actually running:
+
+```bash
+hermes cron status
+```
+
+If the gateway isn't running, your jobs won't execute. Install it as a background service for reliability:
+
+```bash
+hermes gateway install
+# or on Linux servers
+sudo hermes gateway install --system
+```
+
+## Going Further
+
+You've built a working daily briefing bot. Here are some directions to explore next:
+
+- **[Scheduled Tasks (Cron)](/user-guide/features/cron)** — Full reference for schedule formats, repeat limits, and delivery options
+- **[Delegation](/user-guide/features/delegation)** — Deep dive into parallel sub-agent workflows
+- **[Messaging Platforms](/user-guide/messaging)** — Set up Telegram, Discord, or other delivery targets
+- **[Memory](/user-guide/features/memory)** — Persistent context across sessions
+- **[Tips & Best Practices](/guides/tips)** — More prompt engineering advice
+
+:::tip What else can you schedule?
+The briefing bot pattern works for anything: competitor monitoring, GitHub repo summaries, weather forecasts, portfolio tracking, server health checks, or even a daily joke. If you can describe it in a prompt, you can schedule it.
+:::

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/delegation-patterns.md

@@ -0,0 +1,242 @@
+---
+sidebar_position: 13
+title: "Delegation & Parallel Work"
+description: "When and how to use subagent delegation — patterns for parallel research, code review, and multi-file work"
+---
+
+# Delegation & Parallel Work
+
+Hermes can spawn isolated child agents to work on tasks in parallel. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary comes back — intermediate tool calls never enter your context window.
+
+For the full feature reference, see [Subagent Delegation](/user-guide/features/delegation).
+
+---
+
+## When to Delegate
+
+**Good candidates for delegation:**
+- Reasoning-heavy subtasks (debugging, code review, research synthesis)
+- Tasks that would flood your context with intermediate data
+- Parallel independent workstreams (research A and B simultaneously)
+- Fresh-context tasks where you want the agent to approach without bias
+
+**Use something else:**
+- Single tool call → just use the tool directly
+- Mechanical multi-step work with logic between steps → `execute_code`
+- Tasks needing user interaction → subagents can't use `clarify`
+- Quick file edits → do them directly
+- Durable long-running work that must survive session closure or process restart → `cronjob` or `terminal(background=True, notify_on_complete=True)`. Top-level delegation is asynchronous but still process-local.
+
+---
+
+## Pattern: Parallel Research
+
+Research three topics simultaneously and get structured summaries back:
+
+```
+Research these three topics in parallel:
+1. Current state of WebAssembly outside the browser
+2. RISC-V server chip adoption in 2025
+3. Practical quantum computing applications
+
+Focus on recent developments and key players.
+```
+
+Behind the scenes, Hermes uses:
+
+```python
+delegate_task(tasks=[
+    {
+        "goal": "Research WebAssembly outside the browser in 2025",
+        "context": "Focus on: runtimes (Wasmtime, Wasmer), cloud/edge use cases, WASI progress"
+    },
+    {
+        "goal": "Research RISC-V server chip adoption",
+        "context": "Focus on: server chips shipping, cloud providers adopting, software ecosystem"
+    },
+    {
+        "goal": "Research practical quantum computing applications",
+        "context": "Focus on: error correction breakthroughs, real-world use cases, key companies"
+    }
+])
+```
+
+All three run concurrently. Each subagent searches the web independently and returns a summary. The parent agent then synthesizes them into a coherent briefing.
+
+---
+
+## Pattern: Code Review
+
+Delegate a security review to a fresh-context subagent that approaches the code without preconceptions:
+
+```
+Review the authentication module at src/auth/ for security issues.
+Check for SQL injection, JWT validation problems, password handling,
+and session management. Fix anything you find and run the tests.
+```
+
+The key is the `context` field — it must include everything the subagent needs:
+
+```python
+delegate_task(
+    goal="Review src/auth/ for security issues and fix any found",
+    context="""Project at /home/user/webapp. Python 3.11, Flask, PyJWT, bcrypt.
+    Auth files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py
+    Test command: pytest tests/auth/ -v
+    Focus on: SQL injection, JWT validation, password hashing, session management.
+    Fix issues found and verify tests pass."""
+)
+```
+
+:::warning The Context Problem
+Subagents know **absolutely nothing** about your conversation. They start completely fresh. If you delegate "fix the bug we were discussing," the subagent has no idea what bug you mean. Always pass file paths, error messages, project structure, and constraints explicitly.
+:::
+
+---
+
+## Pattern: Compare Alternatives
+
+Evaluate multiple approaches to the same problem in parallel, then pick the best:
+
+```
+I need to add full-text search to our Django app. Evaluate three approaches
+in parallel:
+1. PostgreSQL tsvector (built-in)
+2. Elasticsearch via django-elasticsearch-dsl
+3. Meilisearch via meilisearch-python
+
+For each: setup complexity, query capabilities, resource requirements,
+and maintenance overhead. Compare them and recommend one.
+```
+
+Each subagent researches one option independently. Because they're isolated, there's no cross-contamination — each evaluation stands on its own merits. The parent agent gets all three summaries and makes the comparison.
+
+---
+
+## Pattern: Multi-File Refactoring
+
+Split a large refactoring task across parallel subagents, each handling a different part of the codebase:
+
+```python
+delegate_task(tasks=[
+    {
+        "goal": "Refactor all API endpoint handlers to use the new response format",
+        "context": """Project at /home/user/api-server.
+        Files: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py
+        Old format: return {"data": result, "status": "ok"}
+        New format: return APIResponse(data=result, status=200).to_dict()
+        Import: from src.responses import APIResponse
+        Run tests after: pytest tests/handlers/ -v"""
+    },
+    {
+        "goal": "Update all client SDK methods to handle the new response format",
+        "context": """Project at /home/user/api-server.
+        Files: sdk/python/client.py, sdk/python/models.py
+        Old parsing: result = response.json()["data"]
+        New parsing: result = response.json()["data"] (same key, but add status code checking)
+        Also update sdk/python/tests/test_client.py"""
+    },
+    {
+        "goal": "Update API documentation to reflect the new response format",
+        "context": """Project at /home/user/api-server.
+        Docs at: docs/api/. Format: Markdown with code examples.
+        Update all response examples from old format to new format.
+        Add a 'Response Format' section to docs/api/overview.md explaining the schema."""
+    }
+])
+```
+
+:::tip
+Each subagent gets its own terminal session. They can work on the same project directory without stepping on each other — as long as they're editing different files. If two subagents might touch the same file, handle that file yourself after the parallel work completes.
+:::
+
+---
+
+## Pattern: Gather Then Analyze
+
+Use `execute_code` for mechanical data gathering, then delegate the reasoning-heavy analysis:
+
+```python
+# Step 1: Mechanical gathering (execute_code is better here — no reasoning needed)
+execute_code("""
+from hermes_tools import web_search, web_extract
+
+results = []
+for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
+    r = web_search(query, limit=5)
+    for item in r["data"]["web"]:
+        results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})
+
+# Extract full content from top 5 most relevant
+urls = [r["url"] for r in results[:5]]
+content = web_extract(urls)
+
+# Save for the analysis step
+import json
+with open("/tmp/ai-funding-data.json", "w") as f:
+    json.dump({"search_results": results, "extracted": content["results"]}, f)
+print(f"Collected {len(results)} results, extracted {len(content['results'])} pages")
+""")
+
+# Step 2: Reasoning-heavy analysis (delegation is better here)
+delegate_task(
+    goal="Analyze AI funding data and write a market report",
+    context="""Raw data at /tmp/ai-funding-data.json contains search results and
+    extracted web pages about AI funding, acquisitions, and IPOs in Q1 2026.
+    Write a structured market report: key deals, trends, notable players,
+    and outlook. Focus on deals over $100M."""
+)
+```
+
+This is often the most efficient pattern: `execute_code` handles the 10+ sequential tool calls cheaply, then a subagent does the single expensive reasoning task with a clean context.
+
+---
+
+## Inherited Tool Access
+
+Subagents inherit the parent's enabled toolsets. `delegate_task` does not accept a model-facing `toolsets` parameter, so delegated work cannot grant itself capabilities that the parent does not have. Configure the parent's tools before starting the conversation when a delegated task needs web, terminal, file, or other access. Hermes still strips child-blocked tools such as `clarify`, `memory`, and `send_message`; children keep `execute_code` for programmatic tool calling.
+
+---
+
+## Constraints
+
+- **Default 10 parallel tasks**: batches default to 10 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml, no hard ceiling, only a floor of 1)
+- **Nested delegation is opt-in**: leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (floor 1, no ceiling); the other three remain blocked. Disable globally via `delegation.orchestrator_enabled: false`.
+
+### Tuning Concurrency and Depth
+
+| Config | Default | Range | Effect |
+|--------|---------|-------|--------|
+| `max_concurrent_children` | 10 | >=1 | Parallel batch size per `delegate_task` call |
+| `max_spawn_depth` | 1 | >=1 | How many delegation levels can spawn further |
+
+Example: running 30 parallel workers with nested subagents:
+
+```yaml
+delegation:
+  max_concurrent_children: 30
+  max_spawn_depth: 2
+```
+
+- **Separate terminals** — each subagent gets its own terminal session with separate working directory and state
+- **No conversation history** — subagents see only the `goal` and `context` the parent agent passes when calling `delegate_task`
+- **Default 250 iterations** — set `delegation.max_iterations` lower in `config.yaml` for fleets of simple tasks to save cost
+- **Not durable** — top-level delegation runs in the background and posts its result back later, but it remains tied to the owning session and Hermes process. Session closure, `/stop`, `/new`, or a process restart can cancel or strand in-progress work. Use `cronjob` or `terminal(background=True, notify_on_complete=True)` for work that must survive those boundaries.
+
+---
+
+## Tips
+
+**Be specific in goals.** "Fix the bug" is too vague. "Fix the TypeError in api/handlers.py line 47 where process_request() receives None from parse_body()" gives the subagent enough to work with.
+
+**Include file paths.** Subagents don't know your project structure. Always include absolute paths to relevant files, the project root, and the test command.
+
+**Use delegation for context isolation.** Sometimes you want a fresh perspective. Delegating forces you to articulate the problem clearly, and the subagent approaches it without the assumptions that built up in your conversation.
+
+**Check results.** Subagent summaries are just that — summaries. If a subagent says "fixed the bug and tests pass," verify by running the tests yourself or reading the diff.
+
+**Failures are surfaced.** A subagent that dies (provider error, timeout, crash) is reported with a clean one-line notice — `⚠️ Subagent failed — "your goal": <reason>` — in the CLI delegation tree and as a chat notice on gateway platforms, even when tool progress is turned off. The parent agent also receives the full error in the tool result.
+
+---
+
+*For the complete delegation reference — all parameters, ACP integration, and advanced configuration — see [Subagent Delegation](/user-guide/features/delegation).*

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/desktop-native-signin.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 18
+title: "Desktop Native Sign-In (RFC 8252)"
+description: "How the Hermes Desktop app signs in to a gated gateway using your system browser and PKCE — no embedded webview, no session cookies"
+---
+
+# Desktop Native Sign-In (RFC 8252)
+
+When the Hermes Desktop app connects to a **gated gateway** (a hosted or
+self-hosted dashboard that sits behind an OAuth provider), it can sign in two
+ways:
+
+1. **Native sign-in (RFC 8252)** — the app opens your **real system browser**,
+   you approve in the browser you already trust, and the app receives tokens it
+   stores as owner-only files in its user-data directory (optionally encrypted
+   with your OS keychain — Settings → Gateway). **No embedded webview, no
+   browser session cookies.** This is the default whenever the gateway
+   supports it.
+2. **Embedded sign-in (legacy fallback)** — the app opens a small in-app
+   browser window and captures the gateway's session cookie. Used automatically
+   when the gateway is an older build that doesn't advertise native sign-in.
+
+You don't choose between these — the app detects what the gateway supports and
+picks the best one. This page explains what happens and why.
+
+## Why native sign-in
+
+Embedding a browser inside a native app for OAuth has well-known downsides:
+the login page can't see your existing browser session (so you re-type
+credentials and re-do MFA), password managers and passkeys often don't work,
+and the app relies on reading a session cookie out of a private webview. RFC
+8252 ("OAuth 2.0 for Native Apps") is the industry best practice that avoids
+all of that: **do the authorization in the system browser and hand the app its
+own tokens.**
+
+For Hermes specifically, native sign-in means:
+
+- **No embedded webview.** The authorization happens in Safari / Chrome /
+  Firefox / Edge — whatever you use — with your logins, extensions, and
+  passkeys intact.
+- **No session cookies.** The app holds an OAuth **access token** (short-lived)
+  and **refresh token**, stored as owner-only files — encrypted at rest via
+  your OS keychain (Electron `safeStorage`) when the opt-in keychain toggle in
+  Settings → Gateway is on. REST calls and WebSocket tickets are authenticated
+  with an `Authorization: Bearer` header, not a cookie jar.
+
+## How it works
+
+```
+Desktop app                Gateway (/auth/native/*)          Nous Portal (IDP)
+   │ 1. open loopback 127.0.0.1:<random port>
+   │ 2. system browser ─►  /auth/native/authorize
+   │    (PKCE challenge)    (starts the normal PKCE login) ─► /oauth/authorize
+   │                        ◄──── code ──── /auth/callback ◄──┘
+   │                        3. mint one-time gateway code
+   │ ◄─ 302 127.0.0.1/cb?code=… ─┘
+   │ 4. POST /auth/native/token (code + PKCE verifier)
+   │ ◄─ 5. { access_token, refresh_token, expires_at } ───────┘
+   │ 6. store in local token store; use Bearer for REST + WS tickets
+```
+
+The gateway **brokers** the flow: it is the authorization server *to the
+desktop app* and an OAuth client *to the upstream identity provider* (Nous
+Portal). This is required because the upstream `client_id` and permitted
+redirect URIs are bound to the gateway's own origin — a desktop app can't be a
+direct client of the Portal. The desktop still gets the full RFC 8252
+experience: its own PKCE pair, its own loopback redirect, and tokens it owns.
+
+**PKCE (RFC 7636)** protects the loopback hop: the one-time gateway code is
+useless without the code verifier, which never leaves the app. The code is
+single-use and short-lived.
+
+## Capability detection & fallback
+
+The desktop reads the gateway's public `/api/status` endpoint, which advertises
+an `auth_flows` array:
+
+| `auth_flows` value | Meaning |
+|--------------------|---------|
+| `["cookie", "native_pkce"]` | Gateway supports native sign-in → the app uses it |
+| `["cookie"]` | Gateway supports only the legacy flow → the app uses the embedded webview |
+| *(field absent)* | Older gateway → the app uses the embedded webview |
+
+If native sign-in is advertised but fails for a local reason — e.g. a security
+tool blocks the loopback listener, or you close the browser tab — the app
+**falls back to the embedded flow automatically** so you can still sign in.
+
+## Token lifecycle
+
+- **Access token**: short-lived (minutes). Sent as `Authorization: Bearer` on
+  every REST call and when minting a WebSocket ticket.
+- **Refresh token**: longer-lived, rotating. When the access token is near
+  expiry the app calls `/auth/native/refresh` to rotate both tokens, then
+  updates its token store.
+- **Terminal expiry**: if the refresh token is dead (expired / revoked /
+  reuse-detected), the app clears its stored tokens and prompts a fresh
+  sign-in.
+- **Sign out**: clears both the stored native tokens and any legacy session
+  cookie for that gateway.
+
+## For gateway operators
+
+Native sign-in is available automatically on any gated gateway with an
+interactive session provider registered. No configuration is required — the
+`/auth/native/*` routes and the `auth_flows` advertisement are part of the
+dashboard-auth subsystem. OAuth providers (e.g. the bundled **Nous** provider)
+broker the upstream IDP redirect; password providers (e.g. the bundled
+**basic-auth** plugin) land the system browser on the gateway's `/login`
+credential form instead — which is what lets OS password managers (macOS
+Passwords, etc.) autofill the form, something no embedded desktop webview can
+offer. Token-only credentials (e.g. drain) are not interactive sign-ins and do
+not advertise `native_pkce`.
+
+The relevant endpoints (all public, pre-auth bootstrap, same as the existing
+`/auth/*` OAuth routes):
+
+- `GET /auth/native/authorize` — starts the brokered PKCE login
+- `POST /auth/native/token` — exchanges the loopback code + verifier for tokens
+- `POST /auth/native/refresh` — rotates tokens from the app's refresh token
+
+## See also
+
+- [OAuth over SSH / Remote Hosts](./oauth-over-ssh.md) — the loopback-callback
+  pattern for provider/MCP OAuth on remote machines.
+- [Run Hermes with Nous Portal](./run-hermes-with-nous-portal.md)