zlej123/stepkeeper

What does stepkeeper do?

<Use_When>

• User shares a YouTube how-to URL and wants a clean, followable text/visual guide.
• User complains that a tutorial's spoken directions are ambiguous and wants the "show me" frame.
• User wants a recipe/procedure saved into a notes app. </Use_When>

<Do_Not_Use_When>

• Video is a talking-head lecture, vlog, review, or podcast with no visually-resolvable actions.
• Content is safety-critical (medical, mains electricity, gas, heavy machinery) — needs an expert-reviewed profile. </Do_Not_Use_When>

<How_To_Run> One command drives analyze → capture → pick → render → export. --language is the document language (BCP-47: en, ko, ja, …), not the video’s spoken language. English how-to videos work with either en or ko output.

1. Fully automatic (no ffmpeg, timestamp links instead of screenshots):

   • Korean doc: stepkeeper <URL> --profile generic --language ko --links-only
   • English doc (English-speaking users): stepkeeper <URL> --profile generic --language en --links-only

2. Fully automatic with screenshots (Gemini picks the frame per guide): stepkeeper <URL> --profile recipe --language en --auto-pick --export goodnotes Review the regenerated picker.html (AI picks pre-selected); if the user corrects any, run python -m stepkeeper.feedback add <semantic-evaluation.json> to log it.

3. Manual/agent frame selection:

   • stepkeeper <URL> --profile recipe --language en
   • Agent path: read the three candidate frames under work/frames/… directly, write picks.json yourself (semantic judgment), then re-run with --picks <picks.json> --export goodnotes (or obsidian/bundle/notion).

Notion export needs NOTION_TOKEN and --parent <page-id>. Artifacts go under the current directory (STEPKEEPER_DATA overrides). </How_To_Run>