better-dsh 0.2.5 → 0.3.0

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

@@ -1,202 +0,0 @@
----
-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

@@ -1,138 +0,0 @@
----
-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

@@ -1,114 +0,0 @@
----
-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

@@ -1,133 +0,0 @@
----
-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