better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/communication/communication-one-three-one-rule.md

@@ -0,0 +1,114 @@
+---
+title: "One Three One Rule — 1-3-1 decision briefs: problem, three options, one pick"
+sidebar_label: "One Three One Rule"
+description: "1-3-1 decision briefs: problem, three options, one pick"
+---
+
+{/* 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. */}
+
+# One Three One Rule
+
+1-3-1 decision briefs: problem, three options, one pick.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/communication/one-three-one-rule` |
+| Path | `optional-skills/communication\one-three-one-rule` |
+| Version | `1.0.0` |
+| Author | Willard Moore |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `communication`, `decision-making`, `proposals`, `trade-offs` |
+
+## 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.
+:::
+
+# 1-3-1 Communication Rule
+
+Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
+
+## When to Use
+
+- The user explicitly asks for a "1-3-1" response.
+- The user says "give me options" or "what are my choices" for a technical decision.
+- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
+- The user needs a proposal they can forward to a team or stakeholder.
+
+Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
+
+## Procedure
+
+1. **Problem** (one sentence)
+   - State the core decision or desired outcome in a single concise sentence.
+   - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
+   - Keep it tight. If you need "and", you're describing two problems.
+
+2. **Options** (exactly three)
+   - Present three distinct, viable approaches labeled A, B, C.
+   - Each option gets a brief description, pros, and cons.
+   - Options should represent genuinely different strategies, not minor variations of the same approach.
+
+3. **Recommendation** (one option)
+   - State which option you recommend and why, based on the user's context and priorities.
+   - Be direct — this is your professional judgment, not a hedge.
+
+4. **Definition of Done**
+   - List the specific success criteria for the recommended option.
+   - These are concrete, verifiable outcomes — not vague aspirations.
+   - If the user picks a different option, revise this section to match.
+
+5. **Implementation Plan**
+   - Concrete steps to execute the recommended option.
+   - Include specific commands, tools, or actions where applicable.
+   - If the user picks a different option, revise this section to match.
+
+## Verification
+
+- Response has exactly one Problem sentence.
+- Response has exactly three Options (A, B, C) with pros and cons for each.
+- Response has a single Recommendation that picks one option with reasoning.
+- Definition of Done and Implementation Plan align with the recommended option.
+- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
+
+## Example
+
+User: "Give me a 1-3-1 for adding retry logic to our API client."
+
+Agent:
+
+**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
+
+**Options:**
+
+- **Option A: Exponential backoff with jitter in a shared utility.**
+  Pros: Simple, well-understood pattern; single implementation shared across all callers.
+  Cons: No circuit-breaking; callers still block during retries.
+
+- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
+  Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
+  Cons: Adds a dependency; decorator pattern can obscure control flow.
+
+- **Option C: Queue-based async retry with dead letter handling.**
+  Pros: Non-blocking; failed calls are tracked and replayable; scales well.
+  Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
+
+**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
+
+**Definition of Done:**
+- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
+- Retries up to 3 times with exponential backoff and jitter.
+- All external API calls route through the retry utility.
+- Logs each retry attempt with endpoint and attempt number.
+- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
+
+**Implementation Plan:**
+1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
+2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
+3. Wrap existing API calls in `api_client.py` with the retry utility.
+4. Add unit tests mocking HTTP responses for each retry scenario.
+5. Verify under load with a simple stress test against a flaky endpoint mock.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-ai-presenter-video.md

@@ -0,0 +1,211 @@
+---
+title: "Ai Presenter Video — Make a verified AI presenter video from script + image"
+sidebar_label: "Ai Presenter Video"
+description: "Make a verified AI presenter video from script + image"
+---
+
+{/* 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. */}
+
+# Ai Presenter Video
+
+Make a verified AI presenter video from script + image.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/ai-presenter-video` |
+| Path | `optional-skills/creative/ai-presenter-video` |
+| Version | `1.0.0` |
+| Author | cclank (https://github.com/cclank/lanshu-create-ai-presenter-video), ported by Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos |
+| Tags | `video`, `presenter`, `avatar`, `lipsync`, `tts`, `captions`, `creative` |
+| Related skills | [`hyperframes`](/docs/user-guide/skills/optional/creative/creative-hyperframes), [`kanban-video-orchestrator`](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator), [`comfyui`](/docs/user-guide/skills/optional/creative/creative-comfyui) |
+
+## 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.
+:::
+
+# AI Presenter Video
+
+Turn a topic (or finished script) plus ONE authorized adult presenter image
+into a complete, publish-ready presenter-led video: locked narration, avatar
+generation with lip-sync QA, captions, deterministic editing, loudness-normalized
+master/share encodes, and machine + visual acceptance reports.
+
+Use this skill for new presenter videos AND for continuing, revising,
+captioning, lip-sync-repairing, or re-exporting an existing presenter-video
+job. The workflow is provider-neutral: pick generation capabilities from what
+is actually available in the session (FAL video/image models via
+`image_generate` and the video-gen plugin, TTS via `text_to_speech`, ASR via
+the whisper/STT tooling, ffmpeg for everything deterministic).
+
+> Ported from cclank/lanshu-create-ai-presenter-video (MIT). Upstream body
+> kept substantively verbatim in `references/`; Hermes adaptations live in
+> this hub file. Scripts are deterministic (no network, no credentials).
+
+## Hermes adaptations (read first)
+
+- **Skill dir resolution** — upstream hardcoded its own agent's skills path.
+  In Hermes the loader expands `${HERMES_SKILL_DIR}` to this skill's installed
+  directory, so every command below uses that token directly:
+
+  ```bash
+  SKILL_DIR="${HERMES_SKILL_DIR}"
+  ```
+
+  Shell variables do not persist between tool calls — re-paste the assignment
+  (or the expanded path) in each terminal call that uses it.
+- **Capability mapping** — where the references say "a voice generation
+  capability", use `text_to_speech` (OpenAI/Edge/ElevenLabs per user config);
+  "presenter/avatar generation" → FAL image-to-video families (Kling, Wan,
+  MiniMax H3 etc.) through the configured video tooling, or an avatar/lipsync
+  endpoint the user has access to; "word-timestamp ASR" → whisper via the STT
+  tooling or `faster-whisper` in a venv; "deterministic compositor" → ffmpeg
+  filtergraphs, or the `hyperframes` skill when installed (the editing
+  reference has a HyperFrames section that maps directly onto it).
+- **Visual QA** — do the "normal-speed visual review" steps with
+  `vision_analyze` on the generated contact sheet plus sampled frames
+  (identity, mouth timing, hands, blinking, continuity). Numeric checks come
+  from the scripts' ffprobe output.
+- **Paid-generation consent** — remote avatar/TTS generation is billable.
+  Follow the upstream operating rules: before the first paid call state the
+  uploaded assets, requested seconds, known cost, pilot size, and retry
+  ceiling, and get the user's explicit go-ahead. Never upload the presenter
+  image to a remote provider before `remote_upload_approved` is true in
+  `job.json`.
+- **Consent flags live under `input`** — `rights_confirmed`,
+  `adult_presenter_confirmed`, `remote_upload_approved`, and
+  `voice_clone_approved` sit inside the `input` object of `job.json` (init
+  flags set them; hand-editing must target `input.*`, not the job root).
+  `manual_input_review.*` sits at the root. `preflight.py` distinguishes
+  `errors` (block everything) from `remote_blockers` (block only remote
+  generation) — local script/audio work may proceed while remote is blocked.
+
+## Workflow
+
+1. **Start or resume a job.** New job:
+
+   ```bash
+   python3 "$SKILL_DIR/scripts/init_job.py" \
+     --job-dir ~/Videos/my-presenter-video \
+     --presenter-image /path/to/presenter.png \
+     --topic "explain context engineering in one minute" \
+     --duration 60 --aspect 9:16 \
+     --rights-confirmed --adult-presenter-confirmed
+   ```
+
+   Use `--script` for an existing script file; other flags: `--voice-sample`,
+   `--supporting-media`, `--width`, `--height`, `--fps`, `--watermark`,
+   `--cta`. For an existing job, read `job.json` + QA reports and resume from
+   the earliest unfinished state — never regenerate accepted work.
+
+2. **Manual input review.** Actually look at the presenter image
+   (`vision_analyze`) and listen to any voice sample; record findings by
+   setting the `manual_input_review` booleans in `job.json`, e.g.:
+
+   ```bash
+   python3 - <<'PY'
+   import json
+   p = "~/Videos/my-presenter-video/job.json"  # expand ~ or use an absolute path
+   import os; p = os.path.expanduser(p)
+   j = json.load(open(p))
+   j["manual_input_review"].update(image_viewed=True, single_clear_face=True,
+                                   image_has_no_unwanted_text=True)
+   json.dump(j, open(p, "w"), indent=2)
+   PY
+   ```
+
+   Then gate:
+
+   ```bash
+   python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
+   ```
+
+   Proceed only when `ok: true`; do remote generation only when
+   `remote_ready: true`. Note: preflight also updates `job.json` in place
+   (records the report path) — re-read it after running rather than editing
+   a stale copy.
+
+3. **Lock content and audio** — read `references/generation.md`. Script →
+   full narration via `text_to_speech` → ASR-verify the narration against the
+   script → record real durations. The locked audio is the master clock for
+   everything downstream.
+
+4. **Plan and generate the presenter** — read `references/generation.md`.
+   Short low-cost pilot first; full run only after the pilot passes identity
+   and mouth-timing review.
+
+5. **Edit** — read `references/editing.md`. Deterministic timeline driven by
+   the locked audio; captions and keyword callouts only after audio and media
+   are final.
+
+6. **Verify and deliver** — read `references/qa-recovery.md`, render, then:
+
+   ```bash
+   bash "$SKILL_DIR/scripts/finalize_delivery.sh" \
+     ~/Videos/my-presenter-video/renders/rendered.mp4 \
+     ~/Videos/my-presenter-video/outputs my-video
+   ```
+
+   The finalizer preserves aspect ratio, runs two-pass loudness normalization
+   (program ≈ −16 LUFS), produces master + share encodes, decode-verifies
+   both, writes a delivery report JSON, and emits a nine-frame contact sheet.
+   Inspect the contact sheet with `vision_analyze` before claiming completion.
+
+## Operating rules (non-negotiable)
+
+- Confirm image rights, adult status, remote-upload approval, and
+  voice-cloning authorization before the relevant remote action.
+- Never infer or clone a real person's voice from an image; use an authorized
+  sample or a stock TTS voice.
+- Lock the complete narration before presenter generation, caption timing, or
+  final scene boundaries.
+- Mute video sources in the final composition; only the approved narration
+  and intentional mix tracks carry audio.
+- Preserve provider request bodies and task IDs (minus credentials/expiring
+  URLs). Poll interrupted work before resubmitting — avoid double billing.
+- Stop after three rejected paid candidates and summarize the failure mode.
+- Do not claim completion until the final files fully decode and the contact
+  sheet or full playback has been reviewed.
+
+## Defaults for minimal input
+
+9:16, 1080×1920, 30fps; topic-derived videos target 45–75s; stock voice when
+no authorized sample; presenter-led layout with hook → 2–4 beats → close;
+no music/CTA unless requested; language inferred from the request.
+
+## Reference routing
+
+- `references/generation.md` — intake, content, voice, capability selection,
+  presenter prompts, paid generation, provider changes.
+- `references/editing.md` — timeline contract, openings/closes, captions,
+  keyword-callout presets, HyperFrames composition, exports.
+- `references/qa-recovery.md` — technical acceptance, visual acceptance, and
+  recovery for lip-sync/identity/hands/exposure/freeze/caption/audio faults.
+
+## Pitfalls
+
+- `preflight.py` requires ffprobe; on a bare box install ffmpeg first.
+- The consent booleans set by init flags land under `input.*`; editing them
+  at the job-json root silently does nothing (preflight keeps blocking).
+- `finalize_delivery.sh` needs bash + jq + awk and a fully decodable input —
+  a truncated render fails the decode check by design, not by accident.
+- Long avatar clips drift: prefer one continuous presenter source sliced on
+  the audio timeline over many regenerated chapter clips (identity drift
+  across regenerations is the #1 visual-QA failure).
+- FAL i2v endpoints cap duration (typically 5–15s); plan chapter-level
+  presenter segments accordingly and reuse the pilot's seed/params for
+  consistency where the endpoint supports it.
+
+## Verification
+
+Validated hands-on (Aug 2026): `init_job.py` → `job.json` with correct state
+machine; `preflight.py` correctly blocked on unreviewed inputs, flipped to
+`ok: true` after review booleans, and kept `remote_ready: false` until
+`input.remote_upload_approved`; `finalize_delivery.sh` on a synthetic 5s
+1080×1920 render produced decode-verified master (631kbit/s) + share encodes,
+delivery-report JSON, and a 9-frame contact sheet, exit 0.

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

@@ -0,0 +1,66 @@
+---
+title: "Archify — Validated interactive HTML diagrams, upstream-maintained"
+sidebar_label: "Archify"
+description: "Validated interactive HTML diagrams, upstream-maintained"
+---
+
+{/* 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. */}
+
+# Archify
+
+Validated interactive HTML diagrams, upstream-maintained.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/archify` |
+| Path | `optional-skills/creative/archify` |
+| Version | `2.17.0` |
+| Author | tt-a1i |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `diagram`, `architecture`, `workflow`, `sequence`, `dataflow`, `state-machine`, `mermaid`, `html`, `svg` |
+| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) |
+
+## 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.
+:::
+
+# Archify (upstream-maintained)
+
+> **Catalog stub.** This entry is maintained upstream at
+> [tt-a1i/archify](https://github.com/tt-a1i/archify): the project ships a
+> self-contained skill directory (`archify/`) with the Node CLI, schemas,
+> renderers, examples and references. `hermes skills install
+> official/creative/archify` pulls the current tree live from that repo
+> (quarantined and scanned like any hub install) — this directory holds only
+> the catalog metadata, so the vendored copy can never go stale.
+
+Archify turns a small typed JSON spec into a self-contained, explorable HTML
+diagram: `architecture`, `workflow`, `sequence`, `dataflow` and `lifecycle`
+(state machine) types, dark/light themes, pan/zoom, search, relationship
+tracing, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. It accepts
+plain-language requirements or pasted Mermaid (`flowchart`, `sequenceDiagram`,
+`stateDiagram`) and can read repository evidence when the diagram must reflect
+real code. Every candidate goes through a 9-check `validate` / `deliver`
+receipt, so the output is verifiable rather than eyeballed.
+
+## Prerequisites
+
+- Node.js 18+ on `PATH` (`node bin/archify.mjs doctor` confirms the install;
+  no `npm install` is needed inside the skill package).
+- Installs pull ~200 files (~8 MB, mostly upstream tests and examples) from
+  GitHub; the fetch is pinned to one tree SHA, recorded in the bundle metadata.
+- Upstream's "Update awareness" step runs `scripts/check-update.mjs`, which
+  reads a release manifest from GitHub and only prints a notice — it never
+  downloads or installs anything. Skip it if outbound calls are unwanted.
+
+After install, the bundled `architecture-diagram` skill remains the
+zero-dependency fallback (it ports the same Cocoon AI lineage archify grew out
+of); prefer archify when the user wants validated receipts, Mermaid conversion,
+sequence/lifecycle types, or export beyond a single HTML file.
+
+Full documentation: https://github.com/tt-a1i/archify#readme