better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md

@@ -0,0 +1,202 @@
+---
+title: "Stripe Link Cli — Agent payments via Stripe Link — cards, SPT, approvals"
+sidebar_label: "Stripe Link Cli"
+description: "Agent payments via Stripe Link — cards, SPT, approvals"
+---
+
+{/* 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. */}
+
+# Stripe Link Cli
+
+Agent payments via Stripe Link — cards, SPT, approvals.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/payments/stripe-link-cli` |
+| Path | `optional-skills/payments\stripe-link-cli` |
+| Version | `0.1.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos |
+| Tags | `Payments`, `Stripe`, `Link`, `Checkout`, `MPP` |
+| Related skills | [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent), [`stripe-projects`](/docs/user-guide/skills/optional/payments/payments-stripe-projects) |
+
+## 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.
+:::
+
+# Stripe Link CLI Skill
+
+Wraps [@stripe/link-cli](https://github.com/stripe/link-cli) so Hermes can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Hermes cannot self-approve.
+
+US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated `[linux, macos]`.
+
+## When to Use
+
+Trigger phrases:
+
+- "buy X", "pay for X", "make a purchase", "complete checkout"
+- "get me a card", "I need a payment method"
+- "log in to Link", "connect my Link wallet"
+- HTTP 402 response from a merchant API with `www-authenticate: ... method="stripe"`
+
+If the user wants a paid API call (HTTP 402, no checkout form), the `card` path is wrong — use SPT via this same skill, or hand off to the `mpp-agent` skill.
+
+## Prerequisites
+
+- Node.js 20+ available on `PATH` (`node --version`)
+- US-based (Link account requirement)
+
+The Link account, payment method, and spend-approval app do NOT need to be set up before Hermes attempts to pay — the CLI walks the user through them on first run:
+
+- A Link account at https://app.link.com — created/linked during first `link-cli` auth
+- At least one payment method — added during first run at https://app.link.com/wallet
+- The Link mobile/web app — opened to approve the first spend request when it's made
+
+No env vars required — auth state is stored locally by the CLI under its own config directory.
+
+## Install
+
+Install once, globally:
+
+```
+npm install -g @stripe/link-cli
+```
+
+Or invoke ad-hoc via `npx @stripe/link-cli`. The skill below uses the installed `link-cli` form.
+
+## How to Run
+
+All commands run through the `terminal` tool. The CLI auto-detects non-TTY callers and emits compact `toon` output by default — fine for the model. Pass `--format json` if a step needs structured fields.
+
+Discover commands: `link-cli --llms-full`.
+Get a command's schema before invoking: `link-cli <command> --schema`.
+
+## Procedure
+
+### 1. Check / establish auth
+
+```
+link-cli auth status
+```
+
+If not authenticated, log in with a clear client name (this label shows in the user's Link app):
+
+```
+link-cli auth login --client-name "Hermes" --interval 5 --timeout 300
+```
+
+The `--interval`/`--timeout` form polls inline so the agent doesn't need to manage a `_next` step. Print the verification URL + phrase to the user and wait for the CLI to return.
+
+**Do not proceed past this step until `auth status` confirms login.**
+
+### 2. Evaluate the merchant before creating a spend request
+
+Decide the credential type:
+
+| Merchant surface | `--credential-type` |
+|---|---|
+| Standard web checkout form / Stripe Elements | `card` (default) |
+| Returns HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` |
+| Returns HTTP 402 without `method="stripe"` | unsupported — stop |
+
+For 402 responses, do NOT decode the challenge manually. Pass the raw header:
+
+```
+link-cli mpp decode --challenge '<full WWW-Authenticate header>'
+```
+
+This validates the challenge and extracts the network ID + decoded request body.
+
+### 3. List payment methods + shipping
+
+```
+link-cli payment-methods list
+link-cli shipping-address list
+```
+
+Use the first entry unless the user specifies otherwise. The `id` from `payment-methods list` is the `--payment-method-id` in the next step.
+
+### 4. Create the spend request
+
+Confirm the final total with the user before issuing this command. Amounts are in cents.
+
+```
+link-cli spend-request create \
+  --payment-method-id <pm_id> \
+  --merchant-name "<name>" \
+  --merchant-url "<url>" \
+  --context "<one sentence: what is being purchased and why>" \
+  --amount <cents> \
+  --line-item "name:<item>,unit_amount:<cents>,quantity:1" \
+  --total "type:total,display_text:Total,amount:<cents>" \
+  --request-approval
+```
+
+For MPP merchants add `--credential-type shared_payment_token`.
+
+`--request-approval` pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout.
+
+### 5. Retrieve the credential — SECURELY
+
+**Do not print card details to stdout.** Use `--output-file` so the PAN never enters the agent's transcript or logs:
+
+```
+link-cli spend-request retrieve <lsrq_id> \
+  --include card \
+  --output-file /tmp/link-card.json \
+  --format json
+```
+
+The file is written with `0600` perms; stdout shows only redacted fields (brand, last4, expiry) plus a `card_output_file` path.
+
+### 6. Use the credential
+
+- For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never `read_file` or `cat` the card file into the agent's reasoning context.
+- For MPP merchants:
+
+  ```
+  link-cli mpp pay <merchant-url> \
+    --spend-request-id <lsrq_id> \
+    --method POST \
+    --data '<json body>'
+  ```
+
+### 7. Clean up
+
+Delete the card file as soon as the purchase is done:
+
+```
+rm -f /tmp/link-card.json
+```
+
+## Optional: run as an MCP server instead
+
+`@stripe/link-cli --mcp` exposes the same commands as MCP tools over stdio. To register it with Hermes' native MCP:
+
+```
+hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"
+```
+
+Then `hermes mcp list` should show `stripe-link`. The same approval rules apply — MCP doesn't bypass the Link app approval step.
+
+## Pitfalls
+
+- **US-only.** Outside the US, `auth login` will fail. Tell the user, don't keep retrying.
+- **Card PAN must never enter agent context.** Use `--output-file` every time. If you've already retrieved without it, immediately `link-cli auth logout` is not enough — the card is one-time-use but rotate hygiene matters.
+- **`--request-approval` blocks until the user acts.** If the user is asleep, the CLI will hit its timeout. Set expectations.
+- **Multi-step `_next` commands.** Some commands return `_next.command` that must be executed to continue. When in doubt, prefer the inline-polling flags (`--interval`/`--timeout`).
+- **Output format defaults to `toon`** in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass `--format json`.
+- **Don't default to `card`.** The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed.
+
+## Verification
+
+```
+link-cli --version && link-cli auth status
+```
+
+Exit code 0 means installed and logged in.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/payments/payments-stripe-projects.md

@@ -0,0 +1,138 @@
+---
+title: "Stripe Projects — Provision SaaS services + sync creds via Stripe Projects"
+sidebar_label: "Stripe Projects"
+description: "Provision SaaS services + sync creds via Stripe Projects"
+---
+
+{/* 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. */}
+
+# Stripe Projects
+
+Provision SaaS services + sync creds via Stripe Projects.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/payments/stripe-projects` |
+| Path | `optional-skills/payments\stripe-projects` |
+| Version | `0.1.0` |
+| Author | Teknium (teknium1), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos |
+| Tags | `Payments`, `Stripe`, `Projects`, `Provisioning`, `Infrastructure` |
+| Related skills | [`stripe-link-cli`](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli), [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent) |
+
+## 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.
+:::
+
+# Stripe Projects Skill
+
+Wraps the [Stripe Projects](https://projects.dev) CLI plugin so Hermes can provision SaaS services (Neon, Twilio, Vercel, etc.), generate and sync credentials into the user's `.env`, and manage billing across providers from one place.
+
+Gated `[linux, macos]` while the broader payments cluster matures on Windows. The Stripe CLI itself is cross-platform; this gate is a posture for the cluster, not a hard limit.
+
+## When to Use
+
+Trigger phrases:
+
+- "set up <provider>", "provision <Neon|Twilio|Vercel|...>", "create a database"
+- "give me a <Postgres|Redis|Twilio number|...> for this project"
+- "manage my stack credentials", "rotate this key", "upgrade my plan"
+- "what providers can I add?"
+
+If the user already has a provider account, this skill can still connect it with `stripe projects link <provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
+
+## Prerequisites
+
+- Stripe CLI installed (Homebrew on macOS, package manager on Linux, or download from https://docs.stripe.com/stripe-cli/install)
+- Stripe Projects plugin installed
+- A Stripe account. If the user doesn't have one yet, the CLI can guide them through sign-in or account creation in the browser during setup.
+
+## Install
+
+macOS:
+
+```
+brew install stripe/stripe-cli/stripe
+stripe plugin install projects
+```
+
+Linux: follow the platform-specific install at https://docs.stripe.com/stripe-cli/install, then:
+
+```
+stripe plugin install projects
+```
+
+## How to Run
+
+All commands run through the `terminal` tool from inside the user's project directory (the CLI writes `.env` and `.projects/vault/vault.json` into the CWD).
+
+## Procedure
+
+### 1. Initialize the project
+
+```
+cd <project-root>
+stripe projects init
+```
+
+This creates `.projects/vault/vault.json` (encrypted credential store) and prepares the project to receive providers.
+
+### 2. Discover available providers
+
+```
+stripe projects catalog
+```
+
+Lists every provider Stripe Projects supports — databases, hosting, auth, AI, analytics, messaging, etc.
+
+### 3. Add a service
+
+```
+stripe projects add <provider>/<service>
+```
+
+Examples:
+
+- `stripe projects add neon/postgres`
+- `stripe projects add twilio/sms`
+- `stripe projects add runloop/sandbox`
+
+The CLI provisions the service in the user's own account with the provider, generates credentials, syncs them into `.env`, and records the resource in the vault. The user may need to confirm a tier selection or pricing prompt.
+
+### 4. Verify
+
+```
+stripe projects list
+```
+
+Should show the newly added provider and its `.env` keys.
+
+### 5. Manage / upgrade / remove
+
+```
+stripe projects upgrade <provider>     # tier change
+stripe projects remove <provider>      # deprovision
+stripe projects rotate <provider>      # rotate credentials
+```
+
+## Pitfalls
+
+- **`.env` writes are real writes.** The CLI appends to whatever `.env` is in the project root. If the user's `.env` is gitignored (normal), the keys land safely; if not, this skill could be a credential-leak vector. Always check `.gitignore` first.
+- **Per-project state.** `.projects/vault/vault.json` is per-project. Provisioning the same service in two different projects creates two separate resources — and two bills.
+- **Billing happens on Stripe's side.** Tier prompts during `add`/`upgrade` are real charges; surface them to the user before confirming.
+- **Provider availability changes.** The catalog grows; if a provider the user names isn't listed, `stripe projects catalog | grep <name>` first instead of failing the `add` call.
+- **Credentials in vault are encrypted but `.env` is plaintext.** Standard `.env` hygiene applies — never commit it.
+- **Removing a service does NOT always destroy the underlying resource.** Some providers leave a paused/dormant resource behind. Check the provider's own dashboard after `remove` for high-cost services (managed databases especially).
+
+## Verification
+
+```
+stripe projects --version && stripe projects list
+```
+
+Exit code 0 inside an initialized project means the plugin is healthy.

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

@@ -0,0 +1,114 @@
+---
+title: "Canvas — Fetch Canvas LMS courses and assignments via API token"
+sidebar_label: "Canvas"
+description: "Fetch Canvas LMS courses and assignments via API token"
+---
+
+{/* 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. */}
+
+# Canvas
+
+Fetch Canvas LMS courses and assignments via API token.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/canvas` |
+| Path | `optional-skills/productivity\canvas` |
+| Version | `1.0.0` |
+| Author | community |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Canvas`, `LMS`, `Education`, `Courses`, `Assignments` |
+
+## 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.
+:::
+
+# Canvas LMS — Course & Assignment Access
+
+Read-only access to Canvas LMS for listing courses and assignments.
+
+## Scripts
+
+- `scripts/canvas_api.py` — Python CLI for Canvas API calls
+
+## Setup
+
+1. Log in to your Canvas instance in a browser
+2. Go to **Account → Settings** (click your profile icon, then Settings)
+3. Scroll to **Approved Integrations** and click **+ New Access Token**
+4. Name the token (e.g., "Hermes Agent"), set an optional expiry, and click **Generate Token**
+5. Copy the token and add to `${HERMES_HOME:-~/.hermes}/.env`:
+
+```
+CANVAS_API_TOKEN=your_token_here
+CANVAS_BASE_URL=https://yourschool.instructure.com
+```
+
+The base URL is whatever appears in your browser when you're logged into Canvas (no trailing slash).
+
+## Usage
+
+```bash
+CANVAS="python $HERMES_HOME/skills/productivity/canvas/scripts/canvas_api.py"
+
+# List all active courses
+$CANVAS list_courses --enrollment-state active
+
+# List all courses (any state)
+$CANVAS list_courses
+
+# List assignments for a specific course
+$CANVAS list_assignments 12345
+
+# List assignments ordered by due date
+$CANVAS list_assignments 12345 --order-by due_at
+```
+
+## Output Format
+
+**list_courses** returns:
+```json
+[{"id": 12345, "name": "Intro to CS", "course_code": "CS101", "workflow_state": "available", "start_at": "...", "end_at": "..."}]
+```
+
+**list_assignments** returns:
+```json
+[{"id": 67890, "name": "Homework 1", "due_at": "2025-02-15T23:59:00Z", "points_possible": 100, "submission_types": ["online_upload"], "html_url": "...", "description": "...", "course_id": 12345}]
+```
+
+Note: Assignment descriptions are truncated to 500 characters. The `html_url` field links to the full assignment page in Canvas.
+
+## API Reference (curl)
+
+```bash
+# List courses
+curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
+  "$CANVAS_BASE_URL/api/v1/courses?enrollment_state=active&per_page=10"
+
+# List assignments for a course
+curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
+  "$CANVAS_BASE_URL/api/v1/courses/COURSE_ID/assignments?per_page=10&order_by=due_at"
+```
+
+Canvas uses `Link` headers for pagination. The Python script handles pagination automatically.
+
+## Rules
+
+- This skill is **read-only** — it only fetches data, never modifies courses or assignments
+- On first use, verify auth by running `$CANVAS list_courses` — if it fails with 401, guide the user through setup
+- Canvas rate-limits to ~700 requests per 10 minutes; check `X-Rate-Limit-Remaining` header if hitting limits
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| 401 Unauthorized | Token invalid or expired — regenerate in Canvas Settings |
+| 403 Forbidden | Token lacks permission for this course |
+| Empty course list | Try `--enrollment-state active` or omit the flag to see all states |
+| Wrong institution | Verify `CANVAS_BASE_URL` matches the URL in your browser |
+| Timeout errors | Check network connectivity to your Canvas instance |

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

@@ -0,0 +1,133 @@
+---
+title: "Decision Questionnaire — Turn an unanswerable decision into a questionnaire doc"
+sidebar_label: "Decision Questionnaire"
+description: "Turn an unanswerable decision into a questionnaire doc"
+---
+
+{/* 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. */}
+
+# Decision Questionnaire
+
+Turn an unanswerable decision into a questionnaire doc.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/productivity/decision-questionnaire` |
+| Path | `optional-skills/productivity\decision-questionnaire` |
+| Version | `1.0.0` |
+| Author | Matt Pocock (mattpocock/skills, to-questionnaire) + Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `questionnaire`, `decision`, `async`, `stakeholder`, `discovery`, `communication` |
+| Related skills | [`meeting-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-meeting-action-items), [`document-to-action-items`](/docs/user-guide/skills/bundled/productivity/productivity-document-to-action-items) |
+
+## 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.
+:::
+
+# Decision Questionnaire
+
+Turns something the user can't answer alone into a **questionnaire**: a
+Markdown document they hand to one person to fill in async, or fill out
+together in a meeting. The recipient holds knowledge the user lacks; the
+questionnaire pulls it out of them.
+
+Ported from mattpocock/skills' MIT-licensed `to-questionnaire` skill.
+
+## When to Use
+
+- A decision blocks on facts or judgment held by someone else (a domain
+  expert, a stakeholder, a vendor contact, ops)
+- The user says "I need to ask X about this" or keeps deferring a decision
+  pending someone else's input
+- Preparing for a meeting where specific answers must come back
+
+Do NOT use when the answer is discoverable from the environment (codebase,
+docs, web) — find it yourself first.
+
+## Core Principle: Interview the Send, Not the Subject
+
+The user cannot answer the subject-matter questions (that's the point), but
+they can ALWAYS answer questions about the send. Interview them only about
+that, in two short exchanges:
+
+1. **Who is it going to?** Role, expertise, relationship to the user. This
+   fixes the questionnaire's tone and how much context it must carry. Done
+   when you know who the recipient is and what they know that the user
+   doesn't.
+2. **What do you need back?** The specific decisions or facts the user
+   can't resolve alone. Done when you have a concrete list of what the user
+   must walk away able to do or decide.
+
+Then **write the questionnaire**: draft questions aimed at the gap between
+what the recipient knows and what the user needs, following the structure
+below. Write it to `decision-questionnaire-<slug>.md` in the current
+directory (slug from the topic) and report the absolute path. Done when the
+file exists and every item from step 2 is covered by a question.
+
+## Document Structure
+
+Frame it as a **discovery questionnaire**: the user lacks context, the
+recipient holds it. Order questions most-important-first (async means you
+may only get one pass). Group under `##` headings by theme once there are
+more than a handful.
+
+Template:
+
+```markdown
+# <Questionnaire title>
+
+**Purpose:** why this questionnaire exists and the decision riding on it.
+
+**From:** <the user> · **To:** <the recipient> ·
+**How your answers will be used:** <where they go>
+
+## Context
+
+One paragraph orienting a recipient who wasn't in the user's head. Enough
+to answer well, not a page.
+
+## How to answer
+
+Deadline and rough effort. Partial answers and "I don't know" are useful:
+flag anything you're unsure of rather than skipping it.
+
+## <Theme heading>
+
+### <One question — a single idea, never compound>
+
+_Why this matters: <one line, only where the question could be misread or
+invite a throwaway answer>._
+
+>
+
+## Anything else?
+
+A closing catch-all: anything we didn't ask that we should know?
+```
+
+Every question gets an answer stub (`>`) directly beneath it.
+
+## Pitfalls
+
+1. **Grilling the user about the subject.** They can't answer it — that's
+   why the document exists. Only interview the send.
+2. **Compound questions.** One idea per question; split "and/or" questions.
+3. **Burying the critical question.** Most-important-first; async
+   recipients fade.
+4. **Context dump.** One orienting paragraph, not the whole history.
+5. **Skipping the "why this matters" line on ambiguous questions.** It's
+   what turns a throwaway answer into a useful one — but don't add it to
+   questions that are already unambiguous.
+
+## Verification
+
+- [ ] Recipient's role/knowledge and the needed outcomes captured in two
+      exchanges before drafting
+- [ ] Every step-2 item covered by at least one question
+- [ ] Questions single-idea, most-important-first, answer stubs present
+- [ ] File written and absolute path reported to the user