Landing Site

Landing site — purpose, UX, and design bar

The front door is site/ (Vite + React + Tailwind, dark-only), deployed to vigiles.sh. This skill is the standard every change is held to. The recurring failure it exists to stop: adding elements instead of removing them, which makes the page feel crowded and template-y ("tilda-like") instead of modern.

The one rule under all the others: when in doubt, REMOVE. Design by subtraction. If deleting an element loses no meaning, delete it. A change that adds a box, a caption, a second button, or a reassurance line is suspect until proven necessary.

Purpose (what the site is for)

• TOP GOAL — maximize the % of visitors who actually RUN npx vigiles audit.

This is the ONE conversion metric every design decision serves. The CTA must be GREAT (frictionless, obvious, always reachable). If a change doesn't help someone run the command, it's not earning its place.

• Audience: developers who already live in agentic-coding tools (Claude Code,

Codex, Cursor). They are skeptical and skim on a phone.

• The wow is the graded report — show the result, don't explain the mechanism.
• Front-door promise: "Lighthouse for your agent harness" — a one-command,

zero-config, nothing-uploaded grade of your skills/hooks/subagents/references.

• **THE DEMO FRAME SERVES FOUR JOBS AT ONCE — design for all four, don't let one

crowd out the rest. (1) INTRO — teach what vigiles is at a glance (the graded report IS the pitch). (2) DEMO — instant real grades with zero effort (the baked FEATURED chips). (3) RUN-IN-BROWSER — grade YOUR public repo live by typing it (GitHub anonymous API; public-only). (4) COMMAND-COPY for the rest — a private or local repo can't run in-browser, so the job there is a clean, obvious COPY of npx vigiles audit (a command hand-off, NOT a fake in-browser run). Two clarity rules fall out and are load-bearing: (a) the frame must always make clear WHICH repo is shown and whether it's a PREDEFINED EXAMPLE (a chip) or YOUR OWN (typed) — never ambiguous; (b) the private-repo path is a first-class affordance, not an afterthought jammed into a sentence — a clean labelled command-copy, verified at 390px.** Don't restate the command in three stacked lines (the header showing $ vigiles audit on top of a highlighted chip that already names it is TMI — the header's job is to IDENTIFY the graded repo + its source, not re-print the command).

• **COPY: concrete over clever, and NEVER plant a doubt the reader didn't arrive

with.** Two real misses this stops: (1) a clever headline that reads as cryptic ("'Valid' is not 'true.'") — lead with the concrete pain ("Valid config. Broken agent."), let the cards below carry the nuance; (2) a DEFENSIVE FAQ that spotlights a weakness the reader hadn't noticed ("Is it stable enough to adopt?" draws the eye to a scary version number) — replace doubt-planters with confidence-builders a skeptic actually asks ("Does anything leave my machine?", "Can I grade a private repo?"). Test each line as a cold skeptic: does it make me MORE or LESS likely to run the command? If less, cut or reframe.

• CREDIBILITY: the demo report shows ONLY REAL scans — never fabricate a result.

The brand is "measured, not claimed", so one hardcoded/fake number in the report retroactively poisons trust in every real finding. A LOCKED tease with HONEST PLACEHOLDERS (em-dash "run to fill", no digits) for a genuinely-can't-run-here thing (model-gated trigger-rate) is fine — it fakes NOTHING. Fabricated "results" for a thing the tool actually computes is NOT — show the REAL computed result or keep it an honest explanatory card OUTSIDE the report frame.

• Lower the friction to try: offer PREFILLED popular OSS repos as one-click

"grade this" chips, so a visitor sees a real report without typing or having a repo of their own. SHIPPED — the FEATURED chips in DemoAudit render baked real reports instantly.

• **SHAREABILITY IS THE GROWTH LOOP — a graded result must be a shareable PUBLIC

LINK, and sharing must be one tap. The conversion metric (run npx vigiles audit) is served not only by the visitor in front of you but by the ones they PULL IN: a grade spreads when people post a repo's report, not the landing page. So (1) every completed grade is a copyable deep-link (vigiles.sh/?repo=owner/repo#try) that AUTO-RUNS the audit on load — the URL IS the share unit; (2) surface a one-tap share on any result (native share sheet on mobile, copy-link elsewhere — the ShareRow in DemoAudit); (3) the deep-link is the same slug the input/chips use, so a shared link, a typed repo, and a chip all resolve to one code path. When you add a new result surface, it MUST carry the share affordance + a stable ?repo= link — a result you can't share is a dead end in the loop. SHIPPED** — keep it working.

• Instrument conversion: analytics on the funnel (command copies, typed submits,

chip tries, re-grades, share clicks). The site is on GitHub Pages, NOT Vercel — so Vercel Analytics does NOT apply. Use a lightweight, privacy-friendly, script-tag analytics for static hosting: Plausible / Fathom / GoatCounter. The funnel is already INSTRUMENTED — track() (site/src/lib/track.ts) fires demo_* events and is a safe no-op until a provider is wired. REMAINING: add the provider script tag to index.html and confirm events land. Analytics carries the OUTCOME kind only, never a typed slug (a private repo name must not leak).

Direction — decisions of record (keep current; this is where the DIRECTION lives)

The strategic calls behind the current site. Update this section when a direction changes — it's the design doc, not just a style guide. Each is a decision that cost real iteration to reach; don't silently undo one.

• **THE DEFAULT DEMO MUST SHOW A CATCH — lead with a real low grade, never a wall of

A's. The FEATURED chips are a genuine F → C → B → A scale on RECOGNIZABLE repos (currently davila7/claude-code-templates F, disler/claude-code-hooks-mastery C, madappgang B, obra/superpowers A). WHY it must be this way: real popular plugins mostly grade A/B on the deterministic axis the browser can run — the dramatic failures (skills don't fire, descriptions collide) live in the model-gated trigger-rate tier the browser CAN'T run — so a clean-looking default argues AGAINST the tool ("everything's fine, why do I need this?"). The default must be a genuinely-broken repo so the wow (the report) shows vigiles catching something. Refreshing the low-grade default (repos get fixed over time): sweep with git clone https://github.com/ then node dist/cli.js audit --json (NOTE: codeload/api.github.com are proxy-blocked in the cloud env — git clone via github.com works). Pick a repo that is (a) recognizable, (b) has OBJECTIVE, one-line-fixable findings (dead tool, invisible skills/ dir, dead hook event — not embarrassing-by-design), so the public grade is fair (the Lighthouse model IS public grades of public artifacts). Bake the report to site/src/demo/reports/ and wire it into FEATURED. The real fix for showing model-tier failures is the backend (roadmap)** — server-side fetch (no proxy block) + a rate-limited model.

• NAMES-BUT-NEVER-EXPLAINS is the #1 copy failure — gloss every concept or cut it.

A cold visitor doesn't know what "linter", "reference", "enforce", "spec", or a category name means. Every concept gets a plain-English gloss on FIRST use, or it's cut. Don't name-drop jargon (the OLD README learned this — "DEFINE HARNESS on first use"; the site regressed and had to relearn it). Test every line as a cold Claude Code/Codex user who's never heard of vigiles.

• FOLD ECHOES INTO THE REPORT — don't add standalone explainer cards. The report

IS the wow. A concept the browser can't show (model-gated trigger-rate, the linter cross-reference that needs your local config) is a dashed CLI-only row INSIDE the report (LockedRow / CliRulesRow in report-view/src/Report.tsx), not a card floating below the frame. If the site explains the report in two places, cut the echo (this is why the Wedge five-category strip and the standalone "Your rules → enforced" card were removed — the report already carries both).

• ONE INPUT AFFORDANCE AT A TIME — Public/Private tabs, not a stack. The hero

input was input + "public API" caption + private command hand-off + privacy line all stacked (crowded). It's now Public | Private tabs in DemoAudit: Public = the live type-a-repo combobox; Private = the npx vigiles audit command copy. One affordance visible at a time.

• HONEST TEASE, NEVER BLUR/FAKE (supersedes any older "render it blurred" note).

The model-gated row uses em-dash placeholders (recall — · precision —), NOT blurred fake numbers. Blur reads as a render bug AND a paywall dark pattern, and fabricating a number breaks "measured, not claimed" — doubly wrong sitting near copy that mocks claimed numbers. If a stronger tease is ever wanted, use a REAL measured number with an example label, never a fabricated/blurred one.

UX requirements

• Command-first. npx vigiles audit is the universal action (works on every

OS, every terminal). It is THE primary CTA. Everything else is secondary.

• The Claude Code deeplink (claude-cli://) is a DESKTOP-ONLY enhancement, never

the primary path — it silently dead-ends on mobile / CC Web / desktop-without-CC. Render it only where it can work; never ship a button that does nothing.

• Be honest on mobile. No dead buttons. Where a desktop-only action can't run,

say so plainly and give the real action (the command) instead.

• One primary action per screen. Secondary actions are quiet — a text link or

a light pill, never a second heavy full-width button competing with the primary.

• Harness-neutral. Say "Claude Code or Codex," don't lead with Claude Code —

it's an implementation detail, not the headline. Don't over-explain internals.

• Low-friction + welcoming. A skimmer should understand what it is and how to

try it within one screen, without reading a wall.

Design bar — modern & minimal (the anti-crowding rules)

Reference the feel of Linear / Vercel / Raycast: confident dark, generous space, few words, one clear focal point per section. NOT a feature-stuffed template.

• Every element must earn its place. Remove anything that only restates another

(a caption repeating the screenshot; a trust line said twice; a redundant subhead).

• Cut any label another element already IMPLIES. A "free & open source" badge is

redundant when a GitHub/star link is present; an "AUDIT A SPECIFIC REPO" badge above a "Grade a specific repo" heading restates it. If the context already tells the reader, the label is noise.

• Every link/CTA is ACTIONABLE and specific. The reader must know exactly what

happens on click. No vague or passive secondary links ("Have Claude Code?…"). If a secondary path isn't worth a clear, concrete action, cut it (or move it to the nav, where a persistent link beats a limp fold link).

• One focal point per section. The eye should land on one thing first.
• Whitespace + typography over boxes. Don't stack 3+ full-width bordered boxes;

that repetition is what reads as crowded. Prefer type hierarchy and space to borders. But whitespace must be intentional — no near-empty viewport voids either.

• Reassurance once, in one line. Trust copy ("nothing uploaded") appears once,

compact — never a 3-line paragraph, never repeated per section.

• Cohesion. The hero (badge + headline + subhead + visual) must read as ONE

idea, each part adding new information. If the subhead just says what the screenshot already shows, cut or sharpen it.

• Restraint in color/emphasis. One accent, semantic band colors that always

mean something (grade bands). Bold one phrase per point, not every clause. No decorative emoji confetti.

• Consistent spacing scale. Don't hand-tune one-off margins that fight the rhythm.

Anti-patterns (things that have gone wrong here)

• Stacking input + big button + 3-line trust + divider + command + caption + another

button on one fold. (Fix: keep ~3 elements, cut the rest.)

• A caption under the product shot restating the product shot.
• Adding a notice/button per problem instead of rethinking the flow.
• Two competing primary CTAs (deeplink + command) with no hierarchy.
• CC-first framing ("runs in your own Claude Code…") as the headline reassurance.
• A desktop-only flow (the Claude Code claude-cli:// deeplink) left visible on mobile as a fallback

that just repeats the command another section already shows — the same npx vigiles audit block in back-to-back sections on the phone. (Fix: hidden sm:block the whole desktop-only section; the hero + CTA already carry it.)

In-browser demo (SHIPPED — the invariants to keep)

The live "grade any repo" demo is BUILT (in DemoAudit.tsx + site/src/demo/): type/paste a public repo or tap a featured chip, it fetches the harness files client-side and runs the SAME compiled engine the CLI does. The rules below are now INVARIANTS to preserve, not future direction.

• Every result is shareable (see the shareability goal above). A completed grade

carries a one-tap share + a stable auto-running ?repo= deep-link. This is a hard requirement of the demo, not a nice-to-have — don't ship a result surface without it.

• In-browser, NOT hosted. The audit compute runs entirely CLIENT-SIDE in the

visitor's browser (fetch the repo's files via the GitHub API, run the pure detectors in JS) → reinforces "nothing leaves your machine"; zero backend/cost. The only "hosting" is static file serving on vigiles.sh, like the current site. A cached-serverless backend is explicitly NOT the plan.

• Deterministic-only compute. Run the model-free rings (Truthfulness / Structure /

Safety-via-lethal-trifecta / description-overlap). Skip the model-gated trigger-rate — that's the part that needs an LLM + quota.

• A real progress bar / streaming state while the audit runs — fetching files,

running each ring — never a dead spinner. It should feel like work is happening.

• TEASE the locked LLM part with HONEST placeholders, NOT blur (see the

"HONEST TEASE, NEVER BLUR/FAKE" decision above — this supersedes the earlier "render it blurred" guidance). The model-gated trigger-rate is a dashed CLI-only row IN the report (LockedRow) with em-dash placeholders (recall — · precision —, "run to fill") and an explicit "Copy prompt →" that says what it copies — so people are curious to run it locally, and NOTHING is fabricated. Blur reads as a render failure / paywall and fakes a number; don't.

• Reuse the real report components (render from the AuditReport JSON) — never a

screenshot. This is why the report view lives in a SHARED package (see below).

Repo structure for shared UI (SHIPPED — the invariant to keep)

The audit report (report/) and the landing site (site/) share the same report view via a workspace package — @vigiles/report-view (packages/report-view/), which renders an AuditReport and owns the Report component (variant: "summary" for the in-demo frame, "full" for the CLI's standalone HTML report), the schema, the band tokens, and theme.css. Wired as npm WORKSPACES (workspaces: [packages/*, report, site]). The invariant: the demo and the CLI report render from the SAME component + the SAME AuditReport JSON — never a screenshot, never a duplicated or relative-cross-imported component. A consumer must @source this package's src (Tailwind v4 ignores node_modules). The root vigiles published package + its CI gates

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zernie
• Source: zernie/vigiles
• License: MIT
• Homepage: https://vigiles.sh

Install and usage instructions live in the source repository linked above.