better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/productivity/productivity-here-now.md

@@ -0,0 +1,231 @@
+---
+title: "Here Now — Publish sites to {slug}.here.now and store files in Drives"
+sidebar_label: "Here Now"
+description: "Publish sites to {slug}.here.now and store files in Drives"
+---
+
+{/* 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. */}
+
+# Here Now
+
+Publish sites to {slug}.here.now and store files in Drives.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/here-now` |
+| Path | `optional-skills/productivity\here-now` |
+| Version | `1.15.3` |
+| Author | here.now |
+| License | MIT |
+| Platforms | macos, linux |
+| Tags | `here.now`, `herenow`, `publish`, `deploy`, `hosting`, `static-site`, `web`, `share`, `URL`, `drive`, `storage` |
+
+## 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.
+:::
+
+# here.now
+
+here.now lets agents publish websites and store private files in cloud Drives.
+
+Use here.now for two jobs:
+
+- **Sites**: publish websites and files at `{slug}.here.now`.
+- **Drives**: store private agent files in cloud folders.
+
+## Current docs
+
+**Before answering questions about here.now capabilities, features, or workflows, read the current docs:**
+
+→ **https://here.now/docs**
+
+Read the docs:
+
+- at the first here.now-related interaction in a conversation
+- any time the user asks how to do something
+- any time the user asks what is possible, supported, or recommended
+- before telling the user a feature is unsupported
+
+Topics that require current docs (do not rely on local skill text alone):
+
+- Drives and Drive sharing
+- custom domains
+- payments and payment gating
+- forking
+- proxy routes and service variables
+- handles and links
+- limits and quotas
+- SPA routing
+- error handling and remediation
+- feature availability
+
+**If docs and live API behavior disagree, trust the live API behavior.**
+
+If the docs fetch fails or times out, continue with the local skill and live API/script output. Prefer live API behavior for active operations.
+
+## Requirements
+
+- Required binaries: `curl`, `file`, `jq`
+- Optional environment variable: `$HERENOW_API_KEY`
+- Optional Drive token variable: `$HERENOW_DRIVE_TOKEN`
+- Optional credentials file: `~/.herenow/credentials`
+- Skill helper paths:
+  - `${HERMES_SKILL_DIR}/scripts/publish.sh` for publishing sites
+  - `${HERMES_SKILL_DIR}/scripts/drive.sh` for private Drive storage
+
+## Create a site
+
+```bash
+PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
+bash "$PUBLISH" {file-or-dir} --client hermes
+```
+
+Outputs the live URL (e.g. `https://bright-canvas-a7k2.here.now/`).
+
+Under the hood this is a three-step flow: create/update -> upload files -> finalize. A site is not live until finalize succeeds.
+
+Without an API key this creates an **anonymous site** that expires in 24 hours.
+With a saved API key, the site is permanent.
+
+**File structure:** For HTML sites, place `index.html` at the root of the directory you publish, not inside a subdirectory. The directory's contents become the site root. For example, publish `my-site/` where `my-site/index.html` exists — don't publish a parent folder that contains `my-site/`.
+
+You can also publish raw files without any HTML. Single files get a rich auto-viewer (images, PDF, video, audio). Multiple files get an auto-generated directory listing with folder navigation and an image gallery.
+
+## Update an existing site
+
+```bash
+PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
+bash "$PUBLISH" {file-or-dir} --slug {slug} --client hermes
+```
+
+The script auto-loads the `claimToken` from `.herenow/state.json` when updating anonymous sites. Pass `--claim-token {token}` to override.
+
+Authenticated updates require a saved API key.
+
+## Use a Drive
+
+Use a Drive when the user wants private cloud storage for agent files: documents, context, memory, plans, assets, media, research, code, and anything else that should persist without being published as a website.
+
+Every signed-in account has a default Drive named `My Drive`.
+
+```bash
+DRIVE="${HERMES_SKILL_DIR}/scripts/drive.sh"
+bash "$DRIVE" default
+bash "$DRIVE" ls "My Drive"
+bash "$DRIVE" put "My Drive" notes/today.md --from ./notes/today.md
+bash "$DRIVE" cat "My Drive" notes/today.md
+bash "$DRIVE" share "My Drive" --perms write --prefix notes/ --ttl 7d
+```
+
+Use scoped Drive tokens for agent-to-agent handoff. If you receive a `herenow_drive` share block, use its `token` as `Authorization: Bearer <token>` against `api_base`, respect `pathPrefix` when present, and preserve ETags on writes. A `pathPrefix` of `null` means full-Drive access. If the skill is available, prefer `drive.sh`; otherwise call the listed API operations directly.
+
+## API key storage
+
+The publish script reads the API key from these sources (first match wins):
+
+1. `--api-key {key}` flag (CI/scripting only — avoid in interactive use)
+2. `$HERENOW_API_KEY` environment variable
+3. `~/.herenow/credentials` file (recommended for agents)
+
+To store a key, write it to the credentials file:
+
+```bash
+mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
+```
+
+**IMPORTANT**: After receiving an API key, save it immediately — run the command above yourself. Do not ask the user to run it manually. Avoid passing the key via CLI flags (e.g. `--api-key`) in interactive sessions; the credentials file is the preferred storage method.
+
+Never commit credentials or local state files (`~/.herenow/credentials`, `.herenow/state.json`) to source control.
+
+## Getting an API key
+
+To upgrade from anonymous (24h) to permanent sites:
+
+1. Ask the user for their email address.
+2. Request a one-time sign-in code:
+
+```bash
+curl -sS https://here.now/api/auth/agent/request-code \
+  -H "content-type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+3. Tell the user: "Check your inbox for a sign-in code from here.now and paste it here."
+4. Verify the code and get the API key:
+
+```bash
+curl -sS https://here.now/api/auth/agent/verify-code \
+  -H "content-type: application/json" \
+  -d '{"email":"user@example.com","code":"ABCD-2345"}'
+```
+
+5. Save the returned `apiKey` yourself (do not ask the user to do this):
+
+```bash
+mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials
+```
+
+## State file
+
+After every site create/update, the script writes to `.herenow/state.json` in the working directory:
+
+```json
+{
+  "publishes": {
+    "bright-canvas-a7k2": {
+      "siteUrl": "https://bright-canvas-a7k2.here.now/",
+      "claimToken": "abc123",
+      "claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123",
+      "expiresAt": "2026-02-18T01:00:00.000Z"
+    }
+  }
+}
+```
+
+Before creating or updating sites, you may check this file to find prior slugs.
+Treat `.herenow/state.json` as internal cache only.
+Never present this local file path as a URL, and never use it as source of truth for auth mode, expiry, or claim URL.
+
+## What to tell the user
+
+For published sites:
+
+- Always share the `siteUrl` from the current script run.
+- Read and follow `publish_result.*` lines from script stderr to determine auth mode.
+- When `publish_result.auth_mode=authenticated`: tell the user the site is **permanent** and saved to their account. No claim URL is needed.
+- When `publish_result.auth_mode=anonymous`: tell the user the site **expires in 24 hours**. Share the claim URL (if `publish_result.claim_url` is non-empty and starts with `https://`) so they can keep it permanently. Warn that claim tokens are only returned once and cannot be recovered.
+- Never tell the user to inspect `.herenow/state.json` for claim URLs or auth status.
+
+For Drives:
+
+- Do not describe Drive files as public URLs.
+- Tell the user Drive contents are private unless shared with a scoped token.
+- When sharing access with another agent, prefer a scoped token with a narrow `pathPrefix` and short TTL.
+
+## publish.sh options
+
+| Flag                   | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `--slug {slug}`        | Update an existing site instead of creating |
+| `--claim-token {token}`| Override claim token for anonymous updates    |
+| `--title {text}`       | Viewer title (non-HTML sites)             |
+| `--description {text}` | Viewer description                            |
+| `--ttl {seconds}`      | Set expiry (authenticated only)               |
+| `--client {name}`      | Agent name for attribution (e.g. `hermes`)    |
+| `--base-url {url}`     | API base URL (default: `https://here.now`)    |
+| `--allow-nonherenow-base-url` | Allow sending auth to non-default `--base-url` |
+| `--api-key {key}`      | API key override (prefer credentials file)    |
+| `--spa`                | Enable SPA routing (serve index.html for unknown paths) |
+| `--forkable`           | Allow others to fork this site                           |
+
+## Beyond publish.sh
+
+For Drive operations, use `drive.sh` or the Drive API. For broader account and site management — delete, metadata, passwords, payments, domains, handles, links, variables, proxy routes, forking, duplication, and more — see the current docs:
+
+→ **https://here.now/docs**
+
+Full docs: https://here.now/docs

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/productivity/productivity-live-dashboard.md

@@ -0,0 +1,126 @@
+---
+title: "Live Dashboard — Build self-updating dashboards from live sources"
+sidebar_label: "Live Dashboard"
+description: "Build self-updating dashboards from live sources"
+---
+
+{/* 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. */}
+
+# Live Dashboard
+
+Build self-updating dashboards from live sources.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/live-dashboard` |
+| Path | `optional-skills/productivity/live-dashboard` |
+| Version | `0.2.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `dashboards`, `monitoring`, `status`, `automation`, `reporting` |
+| Related skills | [`product-price-monitor`](/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor), [`competitor-news-monitor`](/docs/user-guide/skills/bundled/research/research-competitor-news-monitor), [`email-inbox-triage`](/docs/user-guide/skills/bundled/email/email-email-inbox-triage), [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) |
+
+## 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.
+:::
+
+# Live Dashboard
+
+Turn one sentence — "make a dashboard for our visa applications, update it daily from the email threads and the case-status site" — into a persistent, self-refreshing status page. The user describes what they want to see; you define the data contract, build a self-contained HTML dashboard, verify one live refresh, then schedule the recurring tick.
+
+Setup runs once in the foreground; the recurring refresh runs as a `cronjob` tick. Installing this skill offers a daily all-dashboards sweep via `/suggestions` (the frontmatter blueprint).
+
+## When to Use
+
+- "Make a dashboard for <project/process> and keep it updated."
+- "I want one place to see the status of <deals / applications / bugs / shipments>."
+- "Track <thing> across my email and <website> and show me where it stands."
+- "Show me the <slug> dashboard." (re-render/preview an existing one)
+- A cron tick fires for an existing dashboard (steps 5-7).
+
+Don't use for: one-off status questions (answer directly), price/availability thresholds on a single item (use `product-price-monitor`), or company news tracking (use `competitor-news-monitor`).
+
+## Prerequisites
+
+- At least one source connector the dashboard will read from: email/calendar via `himalaya` or `google-workspace`, websites via `web_extract` or `browser_navigate`, local files via `read_file`. If none is configured, renegotiate the sources in step 1 before writing any artifact.
+- `cronjob` for the recurring tick.
+- Optional: the `desktop_preview` tool (Hermes desktop app sessions). When it is in the toolset, dashboards render in the in-app preview pane; otherwise the user is given the file path.
+
+## Procedure — Setup (foreground, once)
+
+### 1. Define the dashboard contract
+
+From the user's sentence, pin down: the dashboard's purpose in one line, the entities being tracked (rows), the fields per entity (columns/indicators), what "needs attention" means, the sources each field is read from, and the refresh cadence. Ask about anything ambiguous — a dashboard that tracks the wrong grain is worthless. Done when every field on the dashboard names the source it will be read from.
+
+### 2. Verify each source with one live read
+
+For each source, do one bounded foreground read now: email/calendar via the connector skills (`himalaya`, `google-workspace`), websites via `web_extract` or `browser_navigate`, local files via `read_file`. Record what was actually retrievable — auth walls, missing permissions, or empty results surface here, not on the first scheduled run. Drop or replace sources that fail. Done when every field's source returned real data or was explicitly renegotiated with the user.
+
+### 3. Build the dashboard artifact
+
+Write two files under the Hermes home directory's `dashboards/<slug>/` (the same directory that holds `config.yaml`; never assume a fixed location):
+
+- `dashboard.json` — the contract plus current state: purpose, entities, per-field values, per-field source + retrieval timestamp, a `needs_attention` list, and a change log (append-only, most recent first).
+- `index.html` — a single self-contained HTML page (inline CSS, no external requests) rendering the state: a header with purpose and last-updated time, a "Needs attention" section on top, the entity table, and the recent-changes list. Regenerate it from `dashboard.json` on every refresh; never hand-edit HTML state.
+
+Populate both from the step-2 reads, then show the result (step 8). Done when the page renders the live data and every value on it carries a retrieval timestamp in `dashboard.json`.
+
+### 4. Schedule the refresh
+
+Only after step 3 succeeded, schedule the tick. If the daily all-dashboards sweep from `/suggestions` is already scheduled and its cadence suits, it will pick this dashboard up — say so and stop. Otherwise create a per-dashboard job whose prompt names the state file:
+
+```
+cronjob(action="create",
+        schedule=<cadence from the contract, e.g. "0 8 * * *">,
+        prompt="Load the live-dashboard skill and run the refresh tick for the dashboard at <absolute path to dashboards/<slug>/dashboard.json>.",
+        deliver=<user's destination>)
+```
+
+Pick a cadence that respects source rate limits. Done when a job covering this dashboard exists and its prompt names the state-file path (or the sweep).
+
+## Procedure — Tick (each scheduled run)
+
+### 5. Re-read sources and diff
+
+Load `dashboard.json` (for the sweep: every `dashboards/*/dashboard.json`, one at a time), re-read each field from its named source, and compute a field-level diff against the stored state. A failed source read means unknown state: keep the last good value, mark the field stale with the failure time, and never overwrite good data with an error. Done when every field is either updated, unchanged, or explicitly marked stale.
+
+### 6. Update state and re-render
+
+Apply the diff to `dashboard.json`: update values and timestamps, append material changes to the change log, and recompute `needs_attention` against the contract's attention rules. Regenerate `index.html` from the updated state, then show the result (step 8). Done when the JSON and HTML agree and the change log entry for this run exists (or the run is recorded as no-change).
+
+### 7. Deliver on material change, else stay silent
+
+If the diff contains material changes or new needs-attention items, deliver a short summary: what changed, what needs attention, and where the dashboard is. Otherwise respond with `[SILENT]` — no "still watching" noise unless the user asked for a periodic digest. Done when delivery matches the diff.
+
+## Procedure — Show the dashboard (after every build or re-render, and on request)
+
+### 8. Render where the user can see it
+
+- Desktop/GUI session (`desktop_preview` is in the toolset): `desktop_preview(action="open", url=<absolute path to index.html>, label=<dashboard purpose>)` so the page renders live in the preview pane beside the chat; re-open after each re-render so the pane shows the new state.
+- Any other session (CLI, messenger, cron tick without a GUI): report the absolute path of `index.html` and offer to open it where the platform allows.
+
+Done when the user has either seen the rendered page or been told exactly where it lives.
+
+## Pitfalls
+
+- Building the page before verifying the sources — auth failures then surface on an unattended run.
+- Overwriting last-known-good values with an error page or empty read.
+- Rendering state into HTML only — `dashboard.json` is the source of truth; HTML is a projection.
+- Alerting on every refresh instead of on material change.
+- Tracking the wrong grain (per-thread when the user thinks per-application).
+- Hardcoding the Hermes home path — resolve it from the running install (the directory holding `config.yaml`) and write absolute paths into cron prompts.
+- Calling `desktop_preview` outside a desktop session — it is only in the toolset for GUI sessions; fall back to the path.
+
+## Verification
+
+- [ ] Every dashboard field names its source, and each source passed one foreground read before scheduling.
+- [ ] `dashboard.json` and `index.html` exist and agree; every value carries a retrieval timestamp.
+- [ ] Failed reads marked fields stale without destroying last-known-good state.
+- [ ] Ticks deliver only on material change; no-change runs were `[SILENT]`.
+- [ ] The change log replays the dashboard's history from the state file alone.
+- [ ] The dashboard was shown in the preview pane (desktop) or its path reported (elsewhere).