better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,336 +0,0 @@
----
-title: "Memento Flashcards — Spaced-repetition flashcards: create, review, quiz, export"
-sidebar_label: "Memento Flashcards"
-description: "Spaced-repetition flashcards: create, review, quiz, export"
----
-
-{/* 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. */}
-
-# Memento Flashcards
-
-Spaced-repetition flashcards: create, review, quiz, export.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/productivity/memento-flashcards` |
-| Path | `optional-skills/productivity\memento-flashcards` |
-| Version | `1.0.0` |
-| Author | Memento AI |
-| License | MIT |
-| Platforms | macos, linux |
-| Tags | `Education`, `Flashcards`, `Spaced Repetition`, `Learning`, `Quiz`, `YouTube` |
-
-## 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.
-:::
-
-# Memento Flashcards — Spaced-Repetition Flashcard Skill
-
-## Overview
-
-Memento gives you a local, file-based flashcard system with spaced-repetition scheduling.
-Users can chat with their flashcards by answering in free text and having the agent grade the response before scheduling the next review.
-Use it whenever the user wants to:
-
-- **Remember a fact** — turn any statement into a Q/A flashcard
-- **Study with spaced repetition** — review due cards with adaptive intervals and agent-graded free-text answers
-- **Quiz from a YouTube video** — fetch a transcript and generate a 5-question quiz
-- **Manage decks** — organise cards into collections, export/import CSV
-
-All card data lives in a single JSON file. No external API keys are required — you (the agent) generate flashcard content and quiz questions directly.
-
-User-facing response style for Memento Flashcards:
-- Use plain text only. Do not use Markdown formatting in replies to the user.
-- Keep review and quiz feedback brief and neutral. Avoid extra praise, pep, or long explanations.
-
-## When to Use
-
-Use this skill when the user wants to:
-- Save facts as flashcards for later review
-- Review due cards with spaced repetition
-- Generate a quiz from a YouTube video transcript
-- Import, export, inspect, or delete flashcard data
-
-Do not use this skill for general Q&A, coding help, or non-memory tasks.
-
-## Quick Reference
-
-| User intent | Action |
-|---|---|
-| "Remember that X" / "save this as a flashcard" | Generate a Q/A card, call `memento_cards.py add` |
-| Sends a fact without mentioning flashcards | Ask "Want me to save this as a Memento flashcard?" — only create if confirmed |
-| "Create a flashcard" | Ask for Q, A, collection; call `memento_cards.py add` |
-| "Review my cards" | Call `memento_cards.py due`, present cards one-by-one |
-| "Quiz me on [YouTube URL]" | Call `youtube_quiz.py fetch VIDEO_ID`, generate 5 questions, call `memento_cards.py add-quiz` |
-| "Export my cards" | Call `memento_cards.py export --output PATH` |
-| "Import cards from CSV" | Call `memento_cards.py import --file PATH --collection NAME` |
-| "Show my stats" | Call `memento_cards.py stats` |
-| "Delete a card" | Call `memento_cards.py delete --id ID` |
-| "Delete a collection" | Call `memento_cards.py delete-collection --collection NAME` |
-
-## Card Storage
-
-Cards are stored in a JSON file at:
-
-```
-~/.hermes/skills/productivity/memento-flashcards/data/cards.json
-```
-
-**Never edit this file directly.** Always use `memento_cards.py` subcommands. The script handles atomic writes (write to temp file, then rename) to prevent corruption.
-
-The file is created automatically on first use.
-
-## Procedure
-
-### Creating Cards from Facts
-
-### Activation Rules
-
-Not every factual statement should become a flashcard. Use this three-tier check:
-
-1. **Explicit intent** — the user mentions "memento", "flashcard", "remember this", "save this card", "add a card", or similar phrasing that clearly requests a flashcard → **create the card directly**, no confirmation needed.
-2. **Implicit intent** — the user sends a factual statement without mentioning flashcards (e.g. "The speed of light is 299,792 km/s") → **ask first**: "Want me to save this as a Memento flashcard?" Only create the card if the user confirms.
-3. **No intent** — the message is a coding task, a question, instructions, normal conversation, or anything that is clearly not a fact to memorize → **do NOT activate this skill at all**. Let other skills or default behavior handle it.
-
-When activation is confirmed (tier 1 directly, tier 2 after confirmation), generate a flashcard:
-
-**Step 1:** Turn the statement into a Q/A pair. Use this format internally:
-
-```
-Turn the factual statement into a front-back pair.
-Return exactly two lines:
-Q: <question text>
-A: <answer text>
-
-Statement: "{statement}"
-```
-
-Rules:
-- The question should test recall of the key fact
-- The answer should be concise and direct
-
-**Step 2:** Call the script to store the card:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add \
-  --question "What year did World War 2 end?" \
-  --answer "1945" \
-  --collection "History"
-```
-
-If the user doesn't specify a collection, use `"General"` as the default.
-
-The script outputs JSON confirming the created card.
-
-### Manual Card Creation
-
-When the user explicitly asks to create a flashcard, ask them for:
-1. The question (front of card)
-2. The answer (back of card)
-3. The collection name (optional — default to `"General"`)
-
-Then call `memento_cards.py add` as above.
-
-### Reviewing Due Cards
-
-When the user wants to review, fetch all due cards:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
-```
-
-This returns a JSON array of cards where `next_review_at <= now`. If a collection filter is needed:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due --collection "History"
-```
-
-**Review flow (free-text grading):**
-
-Here is an example of the EXACT interaction pattern you must follow. The user answers, you grade them, tell them the correct answer, then rate the card.
-
-**Example interaction:**
-
-> **Agent:** What year did the Berlin Wall fall?
->
-> **User:** 1991
->
-> **Agent:** Not quite. The Berlin Wall fell in 1989. Next review is tomorrow.
-> *(agent calls: memento_cards.py rate --id ABC --rating hard --user-answer "1991")*
->
-> Next question: Who was the first person to walk on the moon?
-
-**The rules:**
-
-1. Show only the question. Wait for the user to answer.
-2. After receiving their answer, compare it to the expected answer and grade it:
-   - **correct** → user got the key fact right (even if worded differently)
-   - **partial** → right track but missing the core detail
-   - **incorrect** → wrong or off-topic
-3. **You MUST tell the user the correct answer and how they did.** Keep it short and plain-text. Use this format:
-   - correct: "Correct. Answer: &#123;answer&#125;. Next review in 7 days."
-   - partial: "Close. Answer: &#123;answer&#125;. &#123;what they missed&#125;. Next review in 3 days."
-   - incorrect: "Not quite. Answer: &#123;answer&#125;. Next review tomorrow."
-4. Then call the rate command: correct→easy, partial→good, incorrect→hard.
-5. Then show the next question.
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
-  --id CARD_ID --rating easy --user-answer "what the user said"
-```
-
-**Never skip step 3.** The user must always see the correct answer and feedback before you move on.
-
-If no cards are due, tell the user: "No cards due for review right now. Check back later!"
-
-**Retire override:** At any point the user can say "retire this card" to permanently remove it from reviews. Use `--rating retire` for this.
-
-### Spaced Repetition Algorithm
-
-The rating determines the next review interval:
-
-| Rating | Interval | ease_streak | Status change |
-|---|---|---|---|
-| **hard** | +1 day | reset to 0 | stays learning |
-| **good** | +3 days | reset to 0 | stays learning |
-| **easy** | +7 days | +1 | if ease_streak >= 3 → retired |
-| **retire** | permanent | reset to 0 | → retired |
-
-- **learning**: card is actively in rotation
-- **retired**: card won't appear in reviews (user has mastered it or manually retired it)
-- Three consecutive "easy" ratings automatically retire a card
-
-### YouTube Quiz Generation
-
-When the user sends a YouTube URL and wants a quiz:
-
-**Step 1:** Extract the video ID from the URL (e.g. `dQw4w9WgXcQ` from `https://www.youtube.com/watch?v=dQw4w9WgXcQ`).
-
-**Step 2:** Fetch the transcript:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/youtube_quiz.py fetch VIDEO_ID
-```
-
-This returns `{"title": "...", "transcript": "..."}` or an error.
-
-If the script reports `missing_dependency`, tell the user to install it:
-```bash
-pip install youtube-transcript-api
-```
-
-**Step 3:** Generate 5 quiz questions from the transcript. Use these rules:
-
-```
-You are creating a 5-question quiz for a podcast episode.
-Return ONLY a JSON array with exactly 5 objects.
-Each object must contain keys 'question' and 'answer'.
-
-Selection criteria:
-- Prioritize important, surprising, or foundational facts.
-- Skip filler, obvious details, and facts that require heavy context.
-- Never return true/false questions.
-- Never ask only for a date.
-
-Question rules:
-- Each question must test exactly one discrete fact.
-- Use clear, unambiguous wording.
-- Prefer What, Who, How many, Which.
-- Avoid open-ended Describe or Explain prompts.
-
-Answer rules:
-- Each answer must be under 240 characters.
-- Lead with the answer itself, not preamble.
-- Add only minimal clarifying detail if needed.
-```
-
-Use the first 15,000 characters of the transcript as context. Generate the questions yourself (you are the LLM).
-
-**Step 4:** Validate the output is valid JSON with exactly 5 items, each having non-empty `question` and `answer` strings. If validation fails, retry once.
-
-**Step 5:** Store quiz cards:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add-quiz \
-  --video-id "VIDEO_ID" \
-  --questions '[{"question":"...","answer":"..."},...]' \
-  --collection "Quiz - Episode Title"
-```
-
-The script deduplicates by `video_id` — if cards for that video already exist, it skips creation and reports the existing cards.
-
-**Step 6:** Present questions one-by-one using the same free-text grading flow:
-1. Show "Question 1/5: ..." and wait for the user's answer. Never include the answer or any hint about revealing it.
-2. Wait for the user to answer in their own words
-3. Grade their answer using the grading prompt (see "Reviewing Due Cards" section)
-4. **IMPORTANT: You MUST reply to the user with feedback before doing anything else.** Show the grade, the correct answer, and when the card is next due. Do NOT silently skip to the next question. Keep it short and plain-text. Example: "Not quite. Answer: &#123;answer&#125;. Next review tomorrow."
-5. **After showing feedback**, call the rate command and then show the next question in the same message:
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
-  --id CARD_ID --rating easy --user-answer "what the user said"
-```
-6. Repeat. Every answer MUST receive visible feedback before the next question.
-
-### Export/Import CSV
-
-**Export:**
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py export \
-  --output ~/flashcards.csv
-```
-
-Produces a 3-column CSV: `question,answer,collection` (no header row).
-
-**Import:**
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py import \
-  --file ~/flashcards.csv \
-  --collection "Imported"
-```
-
-Reads a CSV with columns: question, answer, and optionally collection (column 3). If the collection column is missing, uses the `--collection` argument.
-
-### Statistics
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
-```
-
-Returns JSON with:
-- `total`: total card count
-- `learning`: cards in active rotation
-- `retired`: mastered cards
-- `due_now`: cards due for review right now
-- `collections`: breakdown by collection name
-
-## Pitfalls
-
-- **Never edit `cards.json` directly** — always use the script subcommands to avoid corruption
-- **Transcript failures** — some YouTube videos have no English transcript or have transcripts disabled; inform the user and suggest another video
-- **Optional dependency** — `youtube_quiz.py` needs `youtube-transcript-api`; if missing, tell the user to run `pip install youtube-transcript-api`
-- **Large imports** — CSV imports with thousands of rows work fine but the JSON output may be verbose; summarize the result for the user
-- **Video ID extraction** — support both `youtube.com/watch?v=ID` and `youtu.be/ID` URL formats
-
-## Verification
-
-Verify the helper scripts directly:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add --question "Capital of France?" --answer "Paris" --collection "General"
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
-```
-
-If you are testing from the repo checkout, run:
-
-```bash
-pytest tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q
-```
-
-Agent-level verification:
-- Start a review and confirm feedback is plain text, brief, and always includes the correct answer before the next card
-- Run a YouTube quiz flow and confirm each answer receives visible feedback before the next question

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

@@ -1,121 +0,0 @@
----
-title: "Property Listings — Present property and rental listings as desktop cards"
-sidebar_label: "Property Listings"
-description: "Present property and rental listings as desktop cards"
----
-
-{/* 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. */}
-
-# Property Listings
-
-Present property and rental listings as desktop cards.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/productivity/property-listings` |
-| Path | `optional-skills/productivity/property-listings` |
-| Version | `0.1.0` |
-| Author | Teknium (teknium1), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `property`, `rental`, `real-estate`, `listings`, `desktop`, `cards` |
-
-## 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.
-:::
-
-# Property Listings Skill
-
-Present researched properties as browsable cards in the Hermes desktop transcript.
-This is a presentation recipe, not a listing search service or an investment valuation.
-
-## When to Use
-
-- Presenting property or rental search results, comparing a shortlist, or re-ranking properties.
-- Following up on a property already shown: keep using cards so the shortlist stays comparable.
-- Outside the desktop app, use ordinary Markdown with source links instead; other clients need not render listing fences.
-
-## Prerequisites
-
-- A Hermes desktop conversation for native cards; the backend may be local or remote.
-- Property details supplied by the user or verified through `web_search`, `web_extract`, or the browser tools available in this session.
-- No additional API keys or dependencies are required for card formatting.
-
-## How to Run
-
-Install this optional skill through the Skills catalog, or use `terminal`:
-
-```text
-hermes skills install official/productivity/property-listings
-```
-
-Load it with `skill_view(name="property-listings")` when presenting listings.
-Installing does not retrofit the running conversation's skill index; start a new
-conversation for automatic discovery, or explicitly load the installed skill now.
-
-## Quick Reference
-
-Emit a fenced code block whose language is `listing` and whose body is valid JSON.
-Use one object, an array of objects, or `{ "listings": [...] }` for a comparison.
-
-| Field | Shape and meaning |
-|---|---|
-| `address` | Required nonempty street address or property headline. |
-| `price` | Formatted string including currency and rental period, if applicable. |
-| `beds`, `baths` | Positive numeric counts; omit unknown values. |
-| `size` | Formatted area including units. |
-| `note` | Why this property is worth a look. |
-| `facts` | Array of short verified specs or amenities. |
-| `catches` | Array of risks or questions to verify before a tour. |
-| `images` | Direct HTTPS photo URLs in listing order; the first is the hero. |
-| `links` | Array of `{ "label": "Source", "url": "https://..." }` detail-page links, not search-result URLs. |
-
-## Procedure
-
-1. Gather the address, price, specs, photos and canonical detail URL. Distinguish
-   verified facts from unknowns; do not invent prices, amenities, or photo URLs.
-2. Deduplicate portal mirrors of the same property into one card, retaining useful
-   source links. Keep source dates and availability caveats in the surrounding prose.
-3. Emit the `listing` fence for every property presented, including follow-ups and
-   re-rankings. Keep facts short and put unresolved concerns in `catches`.
-4. Check the JSON before sending. This fictional format example illustrates all fields;
-   replace its values and example URLs with verified listing data:
-
-```listing
-{
-  "address": "12 Example Lane",
-  "price": "$2,400/mo",
-  "beds": 3,
-  "baths": 2.5,
-  "size": "1,600 sqft",
-  "note": "Fits the requested space and budget.",
-  "facts": ["12-month lease", "Covered parking"],
-  "catches": ["Verify pet policy and total move-in fees"],
-  "images": ["https://example.com/property/front.jpg", "https://example.com/property/kitchen.jpg"],
-  "links": [{"label": "Listing details", "url": "https://example.com/property/12"}]
-}
-```
-
-## Pitfalls
-
-- Cards are authored from gathered data, not fetched from a listing URL or embedded portal page.
-- A sparse card needs only an address. Omit unknown fields rather than filling them with guesses.
-- Use direct remote image URLs, not local paths, data URLs, or search-result pages.
-  Expired or blocked images disappear from the gallery; the text and links still matter.
-- Keep a fence to at most 24 properties, 40 images per property, and 12 entries in
-  facts, catches and links. Text fields are truncated to 400 characters by the renderer.
-- Malformed JSON or a card without identity falls back to a plain code block.
-  A valid card is not proof that the underlying listing is current or accurate.
-
-## Verification
-
-- Every presented property has an address and a verified source link; unknowns are explicit.
-- Desktop displays the address, price, specs, facts, catches and links as a native card.
-- Photos form a gallery; selecting a photo opens the lightbox. Three or more photos
-  use a hero-and-supporting-frames mosaic; additional photos remain browsable there.
-- If the card fails to render, validate the fence language and JSON, then preserve a
-  readable Markdown fallback with the same facts and links.