better-dsh 0.2.5 → 0.3.0-c

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

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

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

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