From e27d72dbd4ea87dc0d3c344f1b47e158c566cc92 Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Sat, 8 Aug 2026 11:19:26 -0700 Subject: [PATCH 1/3] feat: illustrated field-manual explainer (explainer.html) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- explainer.html | 975 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 975 insertions(+) create mode 100644 explainer.html diff --git a/explainer.html b/explainer.html new file mode 100644 index 0000000..84d5766 --- /dev/null +++ b/explainer.html @@ -0,0 +1,975 @@ + + + + + +agentic-kit — the field manual + + + + + + + + + +
+ +
+
Field manual · read cover to cover in about ten minutes
+

The toolbox that keeps your AI stack honest.

+

agentic-kit in one sentence: it's one npm package that installs your agentic tooling, heals it every time an upgrade quietly breaks something, and — the part that makes it different — proves the whole stack actually works instead of assuming it does.

+ +
+ pkg @pacphi/agentic-kit + runtime deps zero + node ≥ 22 + platforms macOS · Linux · Windows + license MIT +
+ + +
+ + +
+
PANEL 01Start with why
+

Great tools drift. Trust shouldn't.

+

agentic-kit exists because of a very specific, very modern kind of heartbreak. You wire up an AI agent stack — persistent memory, self-learning, security scanning, background workers — and it's glorious. Then one npm upgrade later, some of it is quietly off. Not crashed. Not erroring. Just… silently doing nothing, while printing "OK."

+

These aren't hypotheticals. Each of these really happened, and each one now has a guard in the kit that traces back to a filed upstream issue:

+ +
+
+
Incident · memory
+

Writes that vanish while printing "OK"

+

npm upgrades drop native SQLite bindings. The memory CLI keeps reporting success — but nothing lands on disk. The kit now does a verified store→disk write and load-tests the natives.

+
+
+
Incident · security
+

A defense layer, silently dead

+

A package the CLI still imported simply stopped shipping (ruflo #2670) — and prompt-injection defense went dark without a peep. The kit proves security end-to-end against the real CLI.

+
+
+
Incident · statusline
+

Status displays that lie by omission

+

Statuslines regenerate themselves without telling you what's actually enabled. The kit's footer shows each segment only when it's genuinely active — an empty footer is information too.

+
+
+
Incident · daemons
+

Background workers burning tokens

+

Unsupervised daemons used to spend real money overnight. The kit sets up local-only ($0) workers by default; token-spending AI workers stay opt-in behind a machine-wide budget.

+
+
+ +
+ + + + + + WHY + trust, proven + HOW + WHAT + + + + + + + + WHY — the belief + A capability you can't prove is on + should be treated as off. + + HOW — the method + Detect drift → converge to healthy → + prove it against the real CLIs. + + WHAT — the artifact + One zero-dependency npm package: + the ak command and its dashboard. + +
DWG 01 · The golden circleafter S. SinekSheet 1 of 2
+
+

Most tooling starts at the outer ring — what it does. agentic-kit starts at the center: the conviction that in a fast-moving agent ecosystem, proof beats promises. Everything else on this page is that belief, mechanized.

+ +
+
The operating principle
+

Upstream ships fast, and that's good. This kit's job is the gap: detect the drift, converge to a healthy state, and prove it — never assume it.

+
+
+ + +
+
PANEL 02What's in the box
+

Open the drawers

+

You install exactly one package by hand. Everything else — the whole stack below — is installed, wired, healed, and verified for you by ak setup. Here's what ends up under management:

+ +
+
+
Drawer A

ruflo (claude-flow)

+
+

The orchestration engine: persistent memory, self-learning, security scanning, swarms, and background workers for Claude Code. The kit installs it globally, builds its native SQLite past npm's allow-scripts gate, and pins its memory store so writes verifiably land.

+
memory + HNSWneural learningaidefence300+ MCP tools
+
+
+
+
Drawer B

agentic-qe

+
+

A quality-engineering fleet: AI test generation, coverage analysis, quality gates, security scans. The kit keeps its companion agentdb CLI pinned to ruflo's bundled version so the shared learning store stays coherent.

+
test generationcoveragequality gatesagentdb pinned
+
+
+
+
Drawer C

RuvNet Brain

+
+

An offline, source-cited knowledge base over the rUv stack (~2 GB, one-time, prompted). It powers the search_ruvnet tool, so answers about ruflo/AgentDB/RVF/SPARC cite real source instead of stale training priors.

+
offline KBcited answersdrift-checked
+
+
+
+
Drawer D

The hosts

+
+

The agent CLIs that drive sessions: Claude Code by default, Codex opt-in (both at once, in "ambidextrous" dual-host mode), and OpenCode as an explicitly-routed third. Absent hosts get installed; externally-managed ones (brew/mise) are detected and never touched.

+
claude — defaultcodex — opt-inopencode — explicit
+
+
+
+
Drawer E

The kit's own surfaces

+
+

What agentic-kit adds on top: an honest statusline footer, a local web dashboard (Overview · Usage · Observability), a maintainer admin panel, and the ak CLI itself — zero runtime dependencies, SQLite embedded.

+
statuslinedashboard :7431admin :7432ak / agentic-kit
+
+
+
+ +

The workbench — every daily-driver verb

+
+
Command
What it does, in a phrase
+
ak
Status plus one suggested next action — the "what should I do?" answer.
+
ak setup
First-time setup for the machine, your user config, and the project you're standing in.
+
ak status
Read-only truth: per-subsystem ✓/⚠/✗, each drift row naming what sync would do about it.
+
ak sync
The one convergence verb: upgrade → heal → verify. When in doubt, run this.
+
ak dashboard
Local web dashboard — localhost-only, token-guarded, observation-only.
+
ak host
See, pick, and reversibly tear down execution hosts, routing, and provider bindings.
+
ak run
Execute a multi-worker activity pipeline (feature, security, refactor…) across hosts.
+
ak about · system
What each component is and why it's there · your machine's actual footprint.
+
ak uninstall
Leave cleanly. Project data is never touched; --purge offers the global packages too.
+
+

Power-user plumbing lives under ak x … (verify, harvest, statusline, mcp pick, reference sync…) — ak --help --all lists the lot. And every mutating command takes --dry-run and prints its plan, with reasons, before touching anything.

+
+ + +
+
PANEL 03How it works
+

The convergence loop

+

Everything the kit does is one loop, run over and over for the life of your machine: detect what's drifted, converge back to healthy, prove the result against the real CLIs. Three verbs, three commands.

+ +
+ + + + + + + + + + + + + + + DETECT + ak status + + + + CONVERGE + ak sync + + + + PROVE + ak x verify · real CLIs + + + the loop runs + for the life of + the machine + + + + upstream ships a new release + (drift enters here) + + + upgrade first, + re-heal what the + upgrade wiped, + self-update last + + + + + health-history ledger + so regressions get flagged + +
DWG 02 · Detect → Converge → Proveruns after every upgradeSheet 2 of 2
+
+ +
+
+
Detect · ak status
+

Truth, not vibes

+

Every subsystem gets a ✓/⚠/✗ — natives load-tested, memory pin checked, hosts and providers compared against what you chose. Each drift row says exactly what sync would do about it.

+
+
+
Converge · ak sync
+

One verb heals everything

+

Upgrades first, then re-applies everything an upgrade wipes: native builds, guidance blocks, provider wiring, routing policy, the Brain. The kit self-updates last, so new code never applies mid-run.

+
+
+
Prove · ak x verify
+

Evidence, end to end

+

Verification runs the real installed CLIs — a memory write that must land on disk, a security scan that must actually scan. If it can't be proven, status says so instead of guessing.

+
+
+ +

What that looks like — a real ak status, from a real machine

+

This is an unedited capture from the maintainer's own machine while writing this page. Note the two ⚠ rows: honest drift, each naming exactly what sync would do about it. A status that's all green all the time isn't honest — this one earns its checkmarks.

+
+
captured live · unedited
+ 
$ ak status
+  ✓ versions    ruflo 3.34.0 (latest)
+  ✓             agentic-qe 3.13.10 (latest)
+  ✓             @openai/codex 0.147.0 (latest)
+  ✓             opencode-ai 1.18.15 (latest)
+  ✓ ruvnet-brain release v4.0.28 (latest)
+  ✓ self        kit 4.0.0-alpha.41 (latest)
+  ✓ natives     native better-sqlite3 in 1 agentdb location(s)
+  ✓             ruflo memory runtime native (memory, cli)
+  ✓ memory      native-agentdb active writer: 2253 active entries
+  ✓ security    @claude-flow/security + aidefence present (defend functional)
+  ✓ learning    1337 patterns learned, 1400 trajectories (this project)
+  ✓ aqe         agentic-qe initialized here; RVF store healthy
+  ✓ agentdb     agentdb 3.0.0-alpha.17 (coherent with ruflo)
+  ✓ mcp         claude-flow registered (user scope), all families allowed
+  ✓ hosts       claude 2.1.226 (external — self-managed)
+  ✓             claude auth: oauth (subscription, $0)
+  ✓             codex 0.147.0 (npm) · oauth (subscription, $0)
+  ✓             opencode 1.18.15 (npm) · oauth (subscription, $0)
+  ⚠ providers   provider config drifted (want claude+codex+opencode)
+                → sync re-applies provider env + aqe router
+  ⚠ routing     12 activities → 12 agent overrides — llm-config.json out of sync
+                → sync re-applies agentOverrides
+  ✓ daemons     2 running (one per active project is expected)
+  ✓ blocks      CLAUDE.md managed blocks in sync (9 in registry)
+  ✓ statusline  activation footer present and current
+  ✓ qe-court    qe-court panel valid (vendor-diverse, jury independent of writer)
+
+

Abridged only by removing a few repeated sub-rows for width — every line shown is verbatim. The full output runs 38 lines and covers 23 subsystems.

+ +

The honesty mechanisms — how "proven" is built in

+
+
🧾

Every guard cites its incident

Each protection traces to a filed upstream issue, with the investigative history archived in docs/archive/. No superstition-driven code.

+
🪧

Managed blocks, never clobbering

Guidance lands between BEGIN/END markers in ~/.claude/CLAUDE.md (and Codex's AGENTS.md) — merged backup-first; your own content is never touched.

+
🔍

Plans before mutations

Every mutating command takes --dry-run and prints its plan with reasons. You always see the impact before anything changes.

+
📉

Regressions get remembered

Every sync appends a health snapshot; status flags backsliding — learning shrank, native slots dropped — instead of letting it pass silently.

+
+ +
Under the hoodPlain Node ≥ 22 ESM with zero runtime dependencies (SQLite embedded), one bin entry, and modules under src/. CI runs the suite on three OSes × Node 22/24/26; a nightly job installs the latest live upstream packages and re-proves the kit against them — so upstream drift is caught the day it ships, not the day it bites you. There's even a monthly dev-container build check.
+
+ + +
+
PANEL 04Who it's for
+

Two chairs at the same workbench

+

The kit was built by and for agentic engineers — people composing multi-agent systems who need their substrate to be provably on. But its "one command, self-healing" shape makes it just as useful if you'd rather never think about any of this. Both chairs are legitimate.

+ +
+
+
Chair one
+

The agentic engineer

+
    +
  • Provable substrate. Memory, learning, and security verified against real CLIs — your agents stand on ground you can trust.
    • +
  • Multi-host routing. Claude for architecture and review, Codex for implementation and testing — per-activity, tunable, with cross-host escalation ladders.
    • +
  • Observability. The dashboard indexes your actual Claude/Codex/OpenCode transcripts: usage, limits, sessions, live agent activity.
    • +
  • Evidence discipline. Provider, model, and billing claims are labeled observed / configured / inferred / unknown — never conflated.
    • +
+
+
+
Chair two
+

The vibe coder

+
    +
  • One command in, one command forever. ak setup once; from then on, "when in doubt, ak sync" is the entire mental model.
    • +
  • Self-healing you never see. Upgrades that would silently break memory or security get caught and repaired before you notice.
    • +
  • A dashboard instead of config archaeology. Open ak dashboard and see what's on — no spelunking through dotfiles.
    • +
  • No spend surprises. Background workers are local-only ($0) by default; anything token-spending is opt-in behind a budget.
    • +
+
+
+

The shared payoff: extra lift. Your AI-assisted sessions inherit persistent memory, grounded knowledge, quality gates, and honest status — without you maintaining any of it by hand.

+
+ + +
+
PANEL 05Setup, dissected
+

What ak setup actually touches

+

One command, three concentric scopes. Knowing which is which is the whole trick to feeling safe: machine scope is global packages, user scope is your config files, project scope only triggers when you run it inside a git repo.

+ +
+
+
Once per machine
+
+

Global tools, built properly

+

Installs/updates ruflo, agentic-qe, and the pinned agentdb CLI globally — shepherding native SQLite builds past npm ≥ 11.17's allow-scripts gate (the usual silent-breakage culprit). Installs any enabled host CLI that's entirely absent.

+
npm i -g, healednatives load-testedhosts installed if absent
+
+
+
then your user-level config —
+
+
Once per user
+
+

Guidance, knowledge, and MCP

+

Merges managed guidance blocks into ~/.claude/CLAUDE.md (and ~/.codex/AGENTS.md on Codex machines), offers one-time MCP registration with a tool-family picker, installs the RuvNet Brain (~2 GB, prompted — skip with --no-ruvnet-brain), and deploys the token-audit skill.

+
managed blocksMCP pickerBrain (prompted)
+
+
+
and, if you're standing in a git repo —
+
+
Per project
+
+

The repo gets its instruments

+

A sanitized ruflo init, an absolute memory-path pin, a verified store→disk write, the statusline footer, and a background daemon with local-only ($0) workers. Fair warning, disclosed up front: project init runs ruflo init --full --force and can replace existing agent configuration — docs/SETUP.md spells out the contract, and --minimal skips project scope entirely.

+
memory pin + proofstatusline$0 daemon--minimal to skip
+
+
+
+ +
Flags worth knowing--yes accepts every prompt (containers, CI) · --codex / --opencode enable extra hosts · --primary-host codex flips who leads · --no-aqe / --no-security / --no-ruvnet-brain trim subsystems · and ak uninstall reverses the footprint cleanly.
+
+ + +
+
PANEL 06The deeper features
+

Where it gets genuinely clever

+

Past the install-and-heal loop, three features do the heavy lifting for day-to-day work: multi-host execution, the honest statusline, and the local dashboard.

+ +
+
Feature file · 01
+

Hosts × providers — two axes, never confused

+

A host is which agent CLI drives the session (Claude Code, Codex, OpenCode). A provider is which LLM serves inference (Anthropic, OpenAI, OpenRouter, Ollama…). The kit keeps these axes independent — OpenRouter is a provider behind a host, not another host — and converges both from one config with API keys kept in the environment, never written to disk.

+

Enable both frontier hosts and the kit seeds a per-activity routing policy — each kind of work goes to the host and model that suits it, and your edits survive every sync:

+
+
Activity
Leads
Why
+
architecture · design · review
claude
deep reasoning
+
implementation · testing
codex
fast iteration
+
security-scan (example)
opencode
explicit route only
+
+

Then ak run feature "add rate limiting" materializes a whole pipeline — architect → coder → tester → reviewer — across hosts, with per-worker escalation ladders and --dry-run printing the exact plan first. Templates: feature, security, refactor, packaging, release.

+
+ +
+
Feature file · 02
+

A statusline that refuses to flatter you

+

Projects set up by the kit get an append-only footer under ruflo's own status line. Every segment appears only when genuinely active — so the line below is a health certificate, not decoration:

+
🧠 SONA patterns/trajectories · 📈 route-RL metrics · 🛡 aidefence · 🧿 Brain KB · ⚙ daemons · 🎓 AQE stats
+

Codex gets a managed native equivalent (ak x statusline codex native), kept converged by sync without rewriting the rest of your Codex config.

+
+ +
+
Feature file · 03
+

The dashboard — observation only, localhost only

+

One command opens a self-contained local web app on 127.0.0.1:7431, guarded by a per-session token, that never mutates anything. Three areas: Overview (what's installed, wired, and routed), Usage (scorecards, limits, and sessions indexed from your local Claude/Codex/OpenCode transcripts), and Observability (live and historical agent activity on an interactive canvas, with masked transcript evidence).

+

Every capture below is real — taken from the maintainer's machine while this page was being written. First, Overview: the same subsystems as ak status, with the two warnings front and center and what sync would do about each:

+
+
127.0.0.1:7431 · #overview/summary · token-guarded
+ ak dashboard Overview area: System overview showing 2 warnings and 21 nominal subsystems, with providers and routing warning cards that each state the exact sync remediation, above a grid of green subsystem chips. +
+

The Usage area turns your local transcripts into a scorecard — sessions, token volume, API-equivalent cost (clearly labeled list-price equivalent, not what a subscription bills), split by host, with a cost-per-day chart and a when-you-work heatmap:

+
+
127.0.0.1:7431 · #usage/scorecard
+ ak dashboard Usage scorecard: 769 sessions, 17.2 billion tokens, 11,044 dollars API-equivalent, 128 engaged hours, 96.8 percent cache read rate, a cost-per-day bar chart, per-host cards for claude, codex and opencode, and a weekly work heatmap. +
+

And Observability, watching live agent activity. This capture is pleasingly recursive: the session it's following is the Claude Code session that was writing this very page:

+
+
127.0.0.1:7431 · #observability/live
+ ak dashboard Observability Live view: one active session in the agentic-kit project, an execution map canvas showing a Claude Code coordinator node marked Process active just now, and a session stream panel awaiting selection. +
+

A maintainer sibling, ak admin on :7432, tracks the project's own telemetry — repo traffic, npm momentum, CI state — with the same token discipline and zero external fetches from the page itself. Notice the tone: tiles say what they count and what they can't ("ak ships no opt-in counter — an honest gap, not a zero"):

+
+
127.0.0.1:7432 · ak admin · maintainer-only
+ ak admin panel: How many people section with tiles for 93 unique repo visitors, 3 contributors, 0 watching, and a deliberately blank opted-in installs tile explaining ak ships no telemetry, plus momentum sparklines for visitors, cloners and npm downloads. +
+
+
+ + +
+
FIELD TESTTry it in the next ten minutes
+

Three ways in — pick your risk appetite

+ +
+
+
Path A · The real thing
+

Install it on your machine

+

Node ≥ 22, npm, and the claude CLI are the whole prerequisite list. Two commands and the loop is yours.

+
Choose ifYou're ready to actually run with it, on real projects.
+
+
+
Path B · Zero footprint
+

A Codespace / dev container

+

Open the repo in GitHub Codespaces and pick the "try the published release" configuration — the kit installs into a disposable container with a sandbox repo, and your machine never knows.

+
Choose ifYou want to poke at it before installing anything locally.
+
+
+
Path C · Clean-room
+

The docker first-use env

+

cd docker && docker compose up --build ak replays a brand-new user's complete first run — install, setup, dashboard — in total isolation from your host tooling.

+
Choose ifYou like watching a full first-install prove itself end to end.
+
+
+ +
+ + 
# Path A, in full — this is genuinely the whole thing:
+npm install -g @pacphi/agentic-kit@next   # alpha channel until 4.0.0 GA
+ak setup       # machine + user + (inside a repo) project — prompts disclosed
+ak status      # see the proof: every subsystem, ✓/⚠/✗
+ak dashboard   # and here's your stack, in a browser
+
+

From then on, the entire maintenance story is one habit: when in doubt, ak sync.

+
+ + +
+
FIELD NOTESThe questions everyone asks
+

Straight answers

+ +
+ Do I need to install ruflo or agentic-qe myself first? +

No — and that's the point. agentic-kit is the only package you install by hand. ak setup installs ruflo, agentic-qe, and friends globally for you, builds their natives properly, then heals and proves them. (If you already have them installed, setup detects and reuses them.)

+
+
+ Will it clobber my existing config? +

Managed content lands inside clearly-marked BEGIN/END blocks, merged backup-first; everything the kit writes is ownership-recorded so ak host off and ak uninstall can strip exactly its own footprint and nothing else. The one loud exception: project setup runs ruflo init --full --force, which can replace existing agent configuration — it's disclosed up front, documented in docs/SETUP.md, and skippable with --minimal.

+
+
+ I only use Claude Code. Is the multi-host stuff going to get in my way? +

No. The default is claude-only, zero change — nothing is written for hosts you haven't enabled, and no routing policy is seeded for claude-only projects. Codex and OpenCode are strictly opt-in (ak setup --codex, ak host pick), and reversible (ak host off).

+
+
+ Does anything phone home or spend tokens without asking? +

The dashboard is offline-first and localhost-only with a per-session token; background daemons run local-only ($0) workers by default, with token-spending AI workers opt-in behind a machine-wide budget. The one deliberate-egress surface, ak admin, proxies GitHub/npm server-side and never exposes your credential to the page.

+
+
+ And if I want out? +

ak uninstall removes the kit's footprint cleanly — project data is never touched — and --purge additionally offers to remove the global packages it installed. --dry-run shows the exact plan first, like every other mutating command.

+
+
+ +
+
Inspected · Converged · Proven
+

agentic-kit · github.com/pacphi/agentic-kit · MIT. This page describes the 4.0 line (currently the @next alpha channel). Command surfaces evolve — ak --help --all and the docs/ folder are always the current truth; the loop above stays true even as the buttons move around.

+

Credits where due: the kit stands on ruflo (claude-flow) by rUv and agentic-qe — it exists to make excellent, fast-moving tools dependable on your machine.

+
+ +
+ + + + From c7d9450f6f21755f6a62812dd7a1eb3a57f7e4b4 Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Sat, 8 Aug 2026 11:26:33 -0700 Subject: [PATCH 2/3] feat: publish the explainer as the repo's GitHub Pages site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .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. --- .github/workflows/pages.yml | 43 +++++++++++++++++++++++++++++++++++++ README.md | 1 + explainer.html | 22 +++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 .github/workflows/pages.yml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..5f7a548 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,43 @@ +name: pages + +# Publishes explainer.html as the repo's GitHub Pages site +# (https://pacphi.github.io/agentic-kit/). The file on main is the single +# source of truth — this workflow just renames it to index.html at deploy +# time, so nothing is committed twice and no gh-pages branch exists. + +on: + push: + branches: [main] + paths: + - 'explainer.html' + - '.github/workflows/pages.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# One deploy at a time; let an in-flight deploy finish rather than cancel. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/checkout@v7 + - name: Stage site (explainer.html -> index.html) + run: | + mkdir -p _site + cp explainer.html _site/index.html + - uses: actions/configure-pages@v6 + - uses: actions/upload-pages-artifact@v5 + with: + path: _site + - id: deployment + uses: actions/deploy-pages@v5 diff --git a/README.md b/README.md index a68a4c7..5c99ad5 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![npm version](https://img.shields.io/npm/v/@pacphi/agentic-kit/next?label=npm%40next)](https://www.npmjs.com/package/@pacphi/agentic-kit) [![node](https://img.shields.io/node/v/@pacphi/agentic-kit)](https://nodejs.org) [![license: MIT](https://img.shields.io/npm/l/@pacphi/agentic-kit)](LICENSE) +[![explainer](https://img.shields.io/badge/explainer-read_the_field_manual-C9581D)](https://pacphi.github.io/agentic-kit/) **One npm package that installs, heals, and *proves* [ruflo](https://github.com/ruvnet/ruflo) (claude-flow) + [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe), grounds them in *RuvNet Brain* — an offline, source-cited knowledge base over the rUv stack — and wires Claude Code + Codex (+ opencode) into one ambidextrous, self-routing setup. macOS · Linux · Windows.** diff --git a/explainer.html b/explainer.html index 84d5766..3b0b252 100644 --- a/explainer.html +++ b/explainer.html @@ -468,6 +468,26 @@ details .a strong{color:var(--ink)} details .a p + p{margin-top:9px} + /* ---------------- fork-me corner ribbon ---------------- */ + .forkme{position:fixed;top:0;right:0;width:172px;height:172px;overflow:hidden;z-index:60;pointer-events:none} + .forkme a{ + position:absolute;display:block;width:270px;top:46px;right:-66px;transform:rotate(45deg); + background:linear-gradient(180deg,var(--tool),var(--tool-deep)); + color:#FFF7EC;text-decoration:none;text-align:center; + font-family:var(--mono);font-size:11.5px;font-weight:600;letter-spacing:.14em;text-transform:uppercase; + padding:9px 0;pointer-events:auto; + border-top:1.5px dashed rgba(255,247,236,.6);border-bottom:1.5px dashed rgba(255,247,236,.6); + box-shadow:0 3px 12px rgba(34,56,44,.35); + } + .forkme a:hover{background:var(--tool-deep)} + .forkme a:focus-visible{outline:2.5px solid var(--pine);outline-offset:2px} + @media(max-width:640px){ + .forkme{width:134px;height:134px} + .forkme a{width:216px;top:34px;right:-56px;font-size:9.5px;letter-spacing:.1em;padding:7px 0} + header .eyebrow{padding-right:76px} + } + @media print{.forkme{display:none}} + footer{margin-top:64px;padding:36px 0 80px;border-top:3px double var(--ink)} footer .stamp-line{ display:inline-block;border:2px solid var(--stamp);border-radius:6px;color:var(--stamp); @@ -480,6 +500,8 @@ +
Fork me on GitHub
+
From ba672e002cc5ab47fa75f7282eaebfa4fa31a4f0 Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Sat, 8 Aug 2026 11:36:27 -0700 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20truthfulness=20pass=20=E2=80=94=20d?= =?UTF-8?q?ashboard=20areas,=20verb=20coverage,=20workflow=20inventory?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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). --- MAINTAINER.md | 15 ++++++++++++++- README.md | 7 +++++-- docs/DASHBOARD.md | 8 ++++---- explainer.html | 6 +++--- 4 files changed, 26 insertions(+), 10 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index 6cbfe44..6ec02b6 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -84,7 +84,7 @@ docs/ UPGRADING.md # upgrade and capability-adoption motion (shipped) archive/ # investigative history behind each guard (not shipped) .github/ - workflows/{ci,release,nightly}.yml + workflows/{ci,release,nightly,devcontainers,pages}.yml dependabot.yml ``` @@ -220,6 +220,19 @@ CI additionally runs a **CLI smoke** against a sandboxed `HOME` (see `ci.yml`): `x reference sync` (asserts managed blocks present), `uninstall --dry-run`. If you change CLI output shape, expect the smoke to catch it. +Two further workflows cover surfaces `ci.yml` doesn't: + +- **`devcontainers.yml`** builds and smoke-tests both dev container configs with + the reference `devcontainer` CLI — on PRs touching what each config depends on + (a `dorny/paths-filter` job scopes the maintainer and consumer jobs + independently) and monthly, to catch base-image or published-package drift with + no repo change. Guide: [docs/DEVCONTAINERS.md](docs/DEVCONTAINERS.md). +- **`pages.yml`** publishes `explainer.html` as the GitHub Pages site + (): on any push to `main` touching that + file, it stages it as `index.html` and deploys. Pages source is "GitHub + Actions" (`build_type: workflow`) — there is no `gh-pages` branch, and the + file on `main` is the single source of truth. + --- ## 5. Branching methodology diff --git a/README.md b/README.md index 5c99ad5..875365f 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,8 @@ ak status read-only dashboard: what's true, what's drifted [--json] [--d ak sync converge to good: upgrade + heal + verify [--dry-run] [--no-upgrade] ak dashboard open the local web dashboard (auto-opens your browser) [--port N] [--no-open] [--live-source 'surface=path'] +ak admin maintainer-only telemetry admin (localhost; GitHub/npm egress) + [--port N] [--no-open] ak about what each installed component is and why it's there ak system machine footprint: install size, runtime, storage, catalog, projects [--deep] [--json] @@ -93,7 +95,6 @@ ak host manage execution hosts, routing, and provider bindings status | pick | refresh | off ak run execute a host-neutral activity pipeline (including explicit OpenCode routes)