mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-26 06:01:49 +00:00
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784)
* docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
This commit is contained in:
Teknium
GitHub
parent
ea2d66ddc0
commit
252d68fd45
181 changed files with 5498 additions and 122 deletions
|
|
@ -19,6 +19,7 @@ Airtable REST API via curl. Records CRUD, filters, upserts.
|
|||
| Version | `1.1.0` |
|
||||
| Author | community |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Airtable`, `Productivity`, `Database`, `API` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
|
|
|||
|
|
@ -16,9 +16,10 @@ Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.
|
|||
|---|---|
|
||||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/productivity/google-workspace` |
|
||||
| Version | `1.0.0` |
|
||||
| Version | `1.1.0` |
|
||||
| Author | Nous Research |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth` |
|
||||
| Related skills | [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) |
|
||||
|
||||
|
|
@ -228,8 +229,36 @@ $GAPI calendar delete EVENT_ID
|
|||
### Drive
|
||||
|
||||
```bash
|
||||
# Search existing files
|
||||
$GAPI drive search "quarterly report" --max 10
|
||||
$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
|
||||
|
||||
# Get metadata for a single file
|
||||
$GAPI drive get FILE_ID
|
||||
|
||||
# Upload a local file (auto-detects MIME type)
|
||||
$GAPI drive upload /path/to/report.pdf
|
||||
$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID
|
||||
|
||||
# Download (binary files download as-is; Google-native files export to a
|
||||
# sensible default — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
|
||||
$GAPI drive download FILE_ID
|
||||
$GAPI drive download DOC_ID --output ~/doc.pdf
|
||||
$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt
|
||||
|
||||
# Create a folder
|
||||
$GAPI drive create-folder "Reports"
|
||||
$GAPI drive create-folder "Q4" --parent FOLDER_ID
|
||||
|
||||
# Share
|
||||
$GAPI drive share FILE_ID --email alice@example.com --role reader
|
||||
$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
|
||||
$GAPI drive share FILE_ID --type anyone --role reader # anyone with link
|
||||
$GAPI drive share FILE_ID --type domain --domain example.com --role reader
|
||||
|
||||
# Delete — defaults to trash (reversible). Use --permanent to skip the trash.
|
||||
$GAPI drive delete FILE_ID
|
||||
$GAPI drive delete FILE_ID --permanent
|
||||
```
|
||||
|
||||
### Contacts
|
||||
|
|
@ -241,6 +270,10 @@ $GAPI contacts list --max 20
|
|||
### Sheets
|
||||
|
||||
```bash
|
||||
# Create a new spreadsheet
|
||||
$GAPI sheets create --title "Q4 Budget"
|
||||
$GAPI sheets create --title "Inventory" --sheet-name "Stock"
|
||||
|
||||
# Read
|
||||
$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
|
||||
|
||||
|
|
@ -254,7 +287,15 @@ $GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
|
|||
### Docs
|
||||
|
||||
```bash
|
||||
# Read
|
||||
$GAPI docs get DOC_ID
|
||||
|
||||
# Create a new Doc (optionally seeded with body text)
|
||||
$GAPI docs create --title "Meeting Notes"
|
||||
$GAPI docs create --title "Draft" --body "First paragraph..."
|
||||
|
||||
# Append text to the end of an existing Doc
|
||||
$GAPI docs append DOC_ID --text "Additional content to append"
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
|
@ -267,12 +308,21 @@ All commands return JSON. Parse with `jq` or read directly. Key fields:
|
|||
- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
|
||||
- **Calendar create**: `{status: "created", id, summary, htmlLink}`
|
||||
- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
|
||||
- **Drive get**: `{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}`
|
||||
- **Drive upload**: `{status: "uploaded", id, name, mimeType, webViewLink}`
|
||||
- **Drive download**: `{status: "downloaded", id, name, path, mimeType}`
|
||||
- **Drive create-folder**: `{status: "created", id, name, webViewLink}`
|
||||
- **Drive share**: `{status: "shared", permissionId, fileId, role, type}`
|
||||
- **Drive delete**: `{status: "trashed" | "deleted", fileId, permanent}`
|
||||
- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
|
||||
- **Sheets get**: `[[cell, cell, ...], ...]`
|
||||
- **Sheets create**: `{status: "created", spreadsheetId, title, spreadsheetUrl}`
|
||||
- **Docs create**: `{status: "created", documentId, title, url}`
|
||||
- **Docs append**: `{status: "appended", documentId, inserted_at, characters}`
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Never send email or create/delete events without confirming with the user first.** Show the draft content and ask for approval.
|
||||
1. **Never send email, create/delete calendar events, delete Drive files, share files, or modify Docs/Sheets without confirming with the user first.** Show what will be done (recipients, file IDs, content, share role) and ask for approval. For `drive delete`, prefer the default trash (reversible) over `--permanent`.
|
||||
2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
|
||||
3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
|
||||
4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
|
||||
|
|
@ -285,6 +335,7 @@ All commands return JSON. Parse with `jq` or read directly. Key fields:
|
|||
| `NOT_AUTHENTICATED` | Run setup Steps 2-5 above |
|
||||
| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3-5 |
|
||||
| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3-5 |
|
||||
| `AUTHENTICATED (partial)` or "Token missing scopes" | New write capabilities (Drive write/delete, Docs create/edit) require re-authorization. `$GSETUP --revoke` then redo Steps 3-5 to grant the upgraded scopes. |
|
||||
| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
|
||||
| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
|
||||
| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Linear: manage issues, projects, teams via GraphQL + curl.
|
|||
| Version | `1.0.0` |
|
||||
| Author | Hermes Agent |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Linear`, `Project Management`, `Issues`, `GraphQL`, `API`, `Productivity` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.
|
|||
| Version | `1.2.0` |
|
||||
| Author | Mibayy |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `maps`, `geocoding`, `places`, `routing`, `distance`, `directions`, `nearby`, `location`, `openstreetmap`, `nominatim`, `overpass`, `osrm` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Edit PDF text/typos/titles via nano-pdf CLI (NL prompts).
|
|||
| Version | `1.0.0` |
|
||||
| Author | community |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `PDF`, `Documents`, `Editing`, `NLP`, `Productivity` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Notion API via curl: pages, databases, blocks, search.
|
|||
| Version | `1.0.0` |
|
||||
| Author | community |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `Notion`, `Productivity`, `Notes`, `Database`, `API` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ Extract text from PDFs/scans (pymupdf, marker-pdf).
|
|||
| Version | `2.3.0` |
|
||||
| Author | Hermes Agent |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
| Tags | `PDF`, `Documents`, `Research`, `Arxiv`, `Text-Extraction`, `OCR` |
|
||||
| Related skills | [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
|
||||
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ Create, read, edit .pptx decks, slides, notes, templates.
|
|||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/productivity/powerpoint` |
|
||||
| License | Proprietary. LICENSE.txt has complete terms |
|
||||
| Platforms | linux, macos, windows |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
title: "Teams Meeting Pipeline"
|
||||
sidebar_label: "Teams Meeting Pipeline"
|
||||
description: "Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions"
|
||||
---
|
||||
|
||||
{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
|
||||
|
||||
# Teams Meeting Pipeline
|
||||
|
||||
Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.
|
||||
|
||||
## Skill metadata
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/productivity/teams-meeting-pipeline` |
|
||||
| Version | `1.1.0` |
|
||||
| Author | Hermes Agent + Teknium |
|
||||
| License | MIT |
|
||||
| Tags | `Teams`, `Microsoft Graph`, `Meetings`, `Productivity`, `Operations` |
|
||||
|
||||
## Reference: full SKILL.md
|
||||
|
||||
:::info
|
||||
The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
|
||||
:::
|
||||
|
||||
# Teams Meeting Pipeline
|
||||
|
||||
Use this skill whenever the user asks about Microsoft Teams meeting summaries, transcripts, recordings, action items, Graph subscriptions, or any operational question about the Teams meeting pipeline. Works in any language — the triggers below are examples, not an exhaustive list.
|
||||
|
||||
Everything operator-facing is a `hermes teams-pipeline` subcommand run via the terminal tool. There are no new model tools for this pipeline — the CLI is the surface.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
The user is asking to:
|
||||
- summarize a Teams meeting / extract action items / pull meeting notes
|
||||
- check pipeline status, inspect a stored meeting job, or see recent meetings
|
||||
- replay / re-run a stored job that failed or needs a fresh summary
|
||||
- validate Microsoft Graph setup after changing env or config
|
||||
- troubleshoot "meeting summary never arrived" or "no new meetings are ingesting"
|
||||
- manage Graph webhook subscriptions (create, renew, delete, inspect)
|
||||
- set up automated subscription renewal (see pitfall below)
|
||||
|
||||
Multilingual trigger examples (not exhaustive):
|
||||
- English: "summarize the Teams meeting", "pipeline status", "replay job X"
|
||||
- Turkish: "Teams meeting özetle", "action item çıkar", "toplantı notu", "pipeline durumu", "replay job"
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before using the pipeline, verify these are set in `~/.hermes/.env`:
|
||||
|
||||
```bash
|
||||
MSGRAPH_TENANT_ID=...
|
||||
MSGRAPH_CLIENT_ID=...
|
||||
MSGRAPH_CLIENT_SECRET=...
|
||||
```
|
||||
|
||||
If any are missing, direct the user to the Azure app registration guide at `/docs/guides/microsoft-graph-app-registration` — they need an Azure AD app registration with admin-consented Graph application permissions before the pipeline will work.
|
||||
|
||||
## Command reference
|
||||
|
||||
### Status and inspection (start here)
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline validate # config snapshot — run first after any change
|
||||
hermes teams-pipeline token-health # Graph token status
|
||||
hermes teams-pipeline token-health --force-refresh # force a fresh token acquisition
|
||||
hermes teams-pipeline list # recent meeting jobs
|
||||
hermes teams-pipeline list --status failed # only failed jobs
|
||||
hermes teams-pipeline show <job-id> # full detail of one job
|
||||
hermes teams-pipeline subscriptions # current Graph webhook subscriptions
|
||||
```
|
||||
|
||||
### Re-running / debugging
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline run <job-id> # replay a stored job (re-summarize, re-deliver)
|
||||
hermes teams-pipeline fetch --meeting-id <id> # dry-run: resolve meeting + transcript without persisting
|
||||
hermes teams-pipeline fetch --join-web-url "<url>" # dry-run by join URL
|
||||
```
|
||||
|
||||
### Subscription management
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline subscribe \
|
||||
--resource communications/onlineMeetings/getAllTranscripts \
|
||||
--notification-url https://<your-public-host>/msgraph/webhook \
|
||||
--client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
|
||||
|
||||
hermes teams-pipeline renew-subscription <sub-id> --expiration <iso-8601>
|
||||
hermes teams-pipeline delete-subscription <sub-id>
|
||||
hermes teams-pipeline maintain-subscriptions # renew near-expiry ones
|
||||
hermes teams-pipeline maintain-subscriptions --dry-run # show what would be renewed
|
||||
```
|
||||
|
||||
## Decision tree for common asks
|
||||
|
||||
- User asks "why didn't I get a summary for today's meeting?" → start with `list --status failed`, then `show <job-id>` on the relevant row. If the job doesn't exist at all, check `subscriptions` — the webhook may have expired (see pitfall below).
|
||||
- User asks "is setup working?" → `validate`, then `token-health`, then `subscriptions`. If all three pass, request a test meeting and check `list` for a fresh row.
|
||||
- User asks "re-run summary for meeting X" → `list` to find the job ID, `run <job-id>` to replay. If it fails again, `show <job-id>` to inspect the error and `fetch --meeting-id` to dry-run the artifact resolution.
|
||||
- User asks "add meeting X to the pipeline" → usually you don't — the pipeline is subscription-driven, not per-meeting. If they want a specific past meeting summarized, use `fetch` to pull transcript + `run` after a job is created.
|
||||
|
||||
## Critical pitfall: Graph subscriptions expire in 72 hours
|
||||
|
||||
Microsoft Graph caps webhook subscriptions at 72 hours and **will not auto-renew them**. If `maintain-subscriptions` is not scheduled, meeting notifications silently stop arriving 3 days after any manual subscription creation.
|
||||
|
||||
When the user reports "the pipeline worked yesterday but nothing is arriving today":
|
||||
1. Run `hermes teams-pipeline subscriptions` — if it's empty or all entries show `expirationDateTime` in the past, that's the cause.
|
||||
2. Recreate with `subscribe` as shown above.
|
||||
3. **Set up automated renewal immediately** via `hermes cron add`, a systemd timer, or plain crontab. The operator runbook at `/docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production` has all three options. 12-hour interval is safe (6x headroom against the 72h limit).
|
||||
|
||||
## Other pitfalls
|
||||
|
||||
- **Transcript not available yet.** Teams takes some time after a meeting ends to generate the transcript artifact. `fetch --meeting-id` on a just-ended meeting may return empty. Wait 2-5 minutes and retry, or let the Graph webhook drive ingestion naturally.
|
||||
- **Delivery mode mismatch.** If summaries are produced (`list` shows success) but nothing lands in Teams, check `platforms.teams.extra.delivery_mode` and the matching target config (`incoming_webhook_url` OR `chat_id` OR `team_id`+`channel_id`). The writer reads these from config.yaml or `TEAMS_*` env vars.
|
||||
- **Graph app permissions.** A token acquires cleanly (`token-health` passes) but Graph API calls return 401/403 when permissions were added but admin consent wasn't re-granted. Have the user revisit the app registration in the Azure portal and click "Grant admin consent" again.
|
||||
|
||||
## Related docs
|
||||
|
||||
Point the user to these when they need more depth than this skill covers:
|
||||
- Azure app registration walkthrough: `/docs/guides/microsoft-graph-app-registration`
|
||||
- Full pipeline setup: `/docs/user-guide/messaging/teams-meetings`
|
||||
- Operator runbook (renewal automation, troubleshooting, go-live checklist): `/docs/guides/operate-teams-meeting-pipeline`
|
||||
- Webhook listener setup: `/docs/user-guide/messaging/msgraph-webhook`
|
||||
Loading…
Add table
Add a link
Reference in a new issue