feat: illustrated explainer, published as the GitHub Pages site - #125
Merged
Conversation
A self-contained, single-file HTML explainer at the repo root, walking the repo Sinek-style — why it exists (drift vs. trust, with the real incidents each guard traces to), what's in the box, how the detect→converge→prove loop works, who it serves (agentic engineers and vibe coders), setup dissected into its three scopes, and the deeper features (hosts×providers routing, statusline, dashboard). Evidence over mockups: embeds an unedited `ak status` capture and four live screenshots (dashboard Overview / Usage / Observability, and ak admin) taken from a real converged machine — the Observability capture is watching the very session that authored the page. No session tokens appear. Fully offline-capable (images inline as data URIs; webfonts degrade gracefully); verified responsive at 1280px and 390px with zero horizontal overflow.
- .github/workflows/pages.yml — Pages source is "GitHub Actions": on pushes to main touching explainer.html, the workflow stages it as _site/index.html and deploys. No gh-pages branch, no duplicate file; explainer.html on main stays the single source of truth. Repo Pages config flipped to build_type=workflow (site: https://pacphi.github.io/agentic-kit/). - explainer.html — adds a "Fork me on GitHub" diagonal corner ribbon, pure CSS in the page's own palette (tool-orange band, stitched edges), linking to the repo; shrinks on small screens, hidden in print, keyboard-focusable. Verified at 1280px/390px, zero overflow. - README.md — badge linking to the published explainer.
…ventory - README: dashboard verb row now describes all five primary areas (About · Overview · Usage · Observability · System) with current deep links, and is condensed with DASHBOARD.md as the authoritative guide; adds the missing `ak admin` line to the quick command block; adds `about` and `system` rows to the verbs table; drops the plumbing `ak x statusline` line from the porcelain quick block (it remains in the `ak x …` paragraph). - explainer.html: dashboard described with all five areas in both places; Usage capture labeled with the real `#usage/score` hash. - MAINTAINER.md: workflow inventory lists all five workflows; documents the devcontainers build check and the Pages deployment. - docs/DASHBOARD.md: System prose now matches its own navigation table and the implementation — seven views (Summary, Advisory, Sessions, Storage, Runtime, Catalog, Projects).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
explainer.html— a self-contained, single-file illustrated field manual at the repo root: why the kit exists (Sinek-style, grounded in the real incidents each guard traces to), what's in the box, the detect→converge→prove loop, who it serves, setup dissected into its three scopes, and the deeper features. Embeds real evidence: an uneditedak statuscapture and four live screenshots (dashboard Overview / Usage / Observability,ak admin) from a converged machine — no session tokens appear. Fully offline-capable; verified responsive at 1280px/390px with zero horizontal overflow..github/workflows/pages.yml) — Pages source is "GitHub Actions" (build_type: workflow, already enabled on the repo): pushes tomaintouchingexplainer.htmlstage it asindex.htmland deploy to https://pacphi.github.io/agentic-kit/. Nogh-pagesbranch, no duplicate file. Includes a themed pure-CSS "Fork me on GitHub" corner ribbon linking back to the repo, plus a README badge to the site.ak adminadded to the quick command block;about/systemverb rows added; MAINTAINER.md workflow inventory covers all five workflows and documents the devcontainers + Pages workflows; DASHBOARD.md System prose corrected to seven views, matching its own nav table andSYSTEM_VIEWSin the implementation.Test plan
pnpm run lint:mdandpnpm run lint:links:internal— cleanactionlintonpages.yml— cleanmain)