{"id":50468002,"url":"https://github.com/ramsani/html-explainer","last_synced_at":"2026-06-01T08:32:44.974Z","repository":{"id":357613787,"uuid":"1235907139","full_name":"ramsani/html-explainer","owner":"ramsani","description":"Credit-first intent-led HTML artifacts for Claude Code","archived":false,"fork":false,"pushed_at":"2026-05-22T06:00:07.000Z","size":781,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T12:43:36.187Z","etag":null,"topics":["ai-agents","claude-code","developer-tools","html-artifacts","visual-explainer"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramsani.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T19:13:58.000Z","updated_at":"2026-05-22T06:00:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ramsani/html-explainer","commit_stats":null,"previous_names":["ramsani/html-explainer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ramsani/html-explainer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsani%2Fhtml-explainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsani%2Fhtml-explainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsani%2Fhtml-explainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsani%2Fhtml-explainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramsani","download_url":"https://codeload.github.com/ramsani/html-explainer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsani%2Fhtml-explainer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","developer-tools","html-artifacts","visual-explainer"],"created_at":"2026-06-01T08:32:44.245Z","updated_at":"2026-06-01T08:32:44.957Z","avatar_url":"https://github.com/ramsani.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# html-explainer\n\n[![CI](https://github.com/ramsani/html-explainer/actions/workflows/ci.yml/badge.svg)](https://github.com/ramsani/html-explainer/actions/workflows/ci.yml)\n![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n![Patterns](https://img.shields.io/badge/patterns-22-blue.svg)\n\n## What It Does\n\n`html-explainer` helps Claude Code create HTML artifacts that are worth opening.\n\nIt is not HTML for decoration. It is HTML when a browser view helps someone inspect evidence, understand risk, compare options, make a decision, continue work, or save useful context for later.\n\nCore path:\n\n```text\nintent -\u003e evidence -\u003e visual understanding -\u003e decision -\u003e next action -\u003e reusable memory\n```\n\nThe user sees a clear artifact. The repo provides the quiet process behind it: routing, evidence checks, delivery audit, goal contracts, optional `/goal` autonomous closeout, local memory, and re-entry prompts.\n\nOpen a demo artifact:\n\n```text\nexamples/before-after-decision.example.html\n```\n\n## Who It Is For\n\nUse it when Claude Code work needs more than a chat answer:\n\n- repo recaps and re-entry;\n- plan, diff, and PR reviews;\n- architecture and workflow maps;\n- research comparisons;\n- decision decks;\n- prompt or agent behavior tuning;\n- thinking through unclear ideas;\n- saving useful artifacts into a local knowledge base.\n\nDo not use it for short answers, single commands, tiny facts, or low-consequence notes.\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ramsani/html-explainer/main/install.sh | bash\n```\n\nRestart Claude Code after installation.\n\nTo inspect first:\n\n```bash\ngit clone https://github.com/ramsani/html-explainer.git /tmp/html-explainer\ncd /tmp/html-explainer\nDRY_RUN=1 INSTALL_UPSTREAM=0 FETCH_EXAMPLES=0 bash install.sh\nbash install.sh\n```\n\nThe installer adds slash commands, the `thariq-html-effectiveness` skill, docs, patterns, runtime scripts, examples, and a managed block in `~/.claude/CLAUDE.md`. Existing content is backed up before replacement.\n\n## First Command To Try\n\nStart here when you are not sure HTML is worth it:\n\n```text\n/pick-the-right-html revisa esta tarea y dime qué artefacto HTML conviene crear. No generes todavía el HTML.\n```\n\nIf you already know you want the artifact:\n\n```text\n/make-the-right-html genera el artefacto HTML correcto con evidencia, riesgos, incertidumbre, siguiente acción y prompt listo para copiar.\n```\n\n## What You Get After One Command\n\n- a local HTML artifact you can open immediately;\n- visible evidence, risk, recommendation, and next action;\n- a quality result before delivery;\n- a save, private, refresh, supersede, discard, or do-not-save decision;\n- a copy-ready continuation prompt;\n- a reusable knowledge-base entry when the artifact is worth keeping.\n\n## Core Commands\n\n| Command | Use it when you want to... |\n|---|---|\n| `/pick-the-right-html` | Decide whether HTML is worth it and which artifact fits. |\n| `/make-the-right-html` | Generate a verified HTML artifact. |\n| `/check-the-plan` | Review a plan before coding. |\n| `/check-the-diff` | Review a diff or PR before accepting it. |\n| `/reenter-project` | Understand a repo quickly and see the next action. |\n| `/build-decision-tool` | Build a temporary editor, triage board, tuner, or config tool. |\n| `/audit-html` | Check whether an existing artifact is actually useful. |\n| `/think-with-me-about` | Turn a vague topic into a visual thinking surface with evidence, stress testing, action, and re-entry. |\n| `/open-html-explainer-memory` | Open the local knowledge base of saved artifacts. |\n\n## What Good Output Looks Like\n\nA good artifact makes the next useful action obvious.\n\nIt should show:\n\n- what the user is trying to decide;\n- what evidence was inspected;\n- what is fact, inference, assumption, or unknown;\n- why HTML helps more than Markdown;\n- the recommendation, risk, and next action early;\n- a copy-ready next prompt;\n- whether to save, keep private, refresh, supersede, discard, or not save it.\n\nInteractive artifacts must produce usable output: copied prompt, Markdown, JSON, config, checklist, issue body, or another exportable result.\n\nGenerated HTML is expected to pass `deliver-artifact.py` at `90+` before delivery. Each HTML command points to a goal contract that defines the completion standard. To activate Claude Code's autonomous `/goal` loop, start the request with `/goal`.\n\n## Local Memory\n\nUseful artifacts can be saved outside the repo under:\n\n```text\n~/.claude/html-explainer/outputs/\n```\n\nThe local knowledge base is:\n\n```bash\nopen ~/.claude/html-explainer/outputs/index.html\n```\n\nIt shows saved pages, topics, Maps of Content, resurfacing suggestions, related artifacts, metadata, local annotations, and copy-ready re-entry prompts.\n\nFrom Claude Code, use:\n\n```text\n/open-html-explainer-memory\n```\n\n## Autonomous Closeout\n\nFor longer work, use Claude Code's `/goal` so Claude keeps going until a verifiable finish line is met:\n\n```text\n/goal html-explainer V1 is complete when all validation scripts and smoke tests pass, README/CI/CONTRIBUTING list the same checks, and git status shows no generated junk.\n```\n\nUse it for audits, PR closure, artifact delivery, memory validation, and V1-style verification. Do not use it for small questions.\n\nGoal contracts are always available as the finish line for each command. The autonomous `/goal` loop runs only when you invoke `/goal` explicitly.\n\nThe scripts remain the cheap CI floor; `/goal` decides whether the whole job is actually finished and whether the result is truly useful from the evidence Claude reports.\n\nEach HTML-producing command points to a reusable goal contract. If HTML is generated, the command must run `deliver-artifact.py` before the final response; the goal contract treats skipped delivery as unfinished work.\n\nExample:\n\n```text\n/goal use /think-with-me-about to analyze this repo's real value. Do not stop until the generated HTML passes deliver-artifact.py at 90+, has 0 hard fails, includes a memory decision, next action, and a copy-ready continuation prompt.\n```\n\nMore examples: [`docs/GOAL_WORKFLOWS.md`](docs/GOAL_WORKFLOWS.md).\n\nThe reusable goal contracts live in [`goals/`](goals/). The completion model is documented in [`docs/COMPLETION_MODEL.md`](docs/COMPLETION_MODEL.md).\n\n## Verify Locally\n\nRun the same checks expected from contributors and CI:\n\n```bash\nbash -n install.sh uninstall.sh scripts/*.sh\nscripts/validate-patterns.sh\nscripts/validate-commands.sh\nscripts/validate-examples.sh\nscripts/validate-goals.sh\nscripts/validate-golden-artifacts.sh\nscripts/validate-scenarios.sh\nscripts/smoke-install.sh\nscripts/smoke-uninstall.sh\nscripts/smoke-artifact-memory.sh\nDRY_RUN=1 INSTALL_UPSTREAM=0 FETCH_EXAMPLES=0 bash install.sh\n```\n\nFor the docs reading order, see [`docs/DOCS_MAP.md`](docs/DOCS_MAP.md).\n\n## Uninstall\n\nPreview:\n\n```bash\nDRY_RUN=1 bash uninstall.sh\n```\n\nRestore latest backup, or remove managed files if no backup exists:\n\n```bash\nbash uninstall.sh\n```\n\nRemove without restoring backup:\n\n```bash\nRESTORE_BACKUP=0 bash uninstall.sh\n```\n\nRemove and delete backups:\n\n```bash\nKEEP_BACKUPS=0 bash uninstall.sh\n```\n\n## Credits\n\nThis project is an independent integration layer inspired by and built around:\n\n- [`visual-explainer`](https://github.com/nicobailon/visual-explainer) by Nico Bailon;\n- [\"The unreasonable effectiveness of HTML\"](https://thariqs.github.io/html-effectiveness/) by Thariq S. Bate;\n- [`skills`](https://github.com/mattpocock/skills) by Matt Pocock.\n\nIt is not an official project of Nico Bailon, Thariq S. Bate, Matt Pocock, Anthropic, or Claude Code.\n\nSee [`CREDITS.md`](CREDITS.md), [`CHANGELOG.md`](CHANGELOG.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsani%2Fhtml-explainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framsani%2Fhtml-explainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsani%2Fhtml-explainer/lists"}