# adom-ui-linter

Deterministic compliance linter for Adom apps. Runs ~50 checks across 6 categories and emits AI hints for every failure.

![Lint output showing passes on adom-step](docs/screenshot-lint-passes.png)

## Why

Skills are large markdown documents the AI reads once and partially forgets after context compaction. The linter converts skill rules into deterministic grep-level checks with structured `Hint:` lines. The AI takes hints from CLI output far more seriously than rules it read 200 messages ago.

Think of it as an **incrementally-revealing skill system**: each failure teaches the AI one specific rule at the exact moment it needs to know.

## Failures with AI hints

When checks fail, the linter emits targeted remediation hints that the AI acts on immediately:

![Failures with hints on adom-desktop](docs/screenshot-lint-failures.png)

## Check catalog

50+ checks across 6 categories:

![All available checks by category](docs/screenshot-checks-catalog.png)

| Category | ID prefix | What it checks |
|---|---|---|
| header | HDR-01..11 | 44px height, .brand/.vsep/.subject, fonts, popover, favicon |
| ui-patterns | UI-01..13 | Tooltips (body-appended, z-99999, not ::after), colors, layout, ALL CAPS |
| ai-drivability | AI-01..07 | GET /state, GET /console, relay User-Agent gate, CLI hints |
| cli-compliance | CLI-01..11 | OK:/ERROR: prefix, Hint: lines, health/install/version, isatty |
| skills-docs | SKL-01..09 | SKILL.md, frontmatter, triggers, hierarchy, README, wiki page |
| build-publish | BLD-01..08 | VERSION file, sync, release profile, publish script, port registry |

## Install

```bash
curl -fsSL https://git-wiki-ktqxite5iglh.adom.cloud/api/v1/pages/adom-ui-linter/assets/adom-ui-linter \
  | sudo tee /usr/local/bin/adom-ui-linter >/dev/null
chmod +x /usr/local/bin/adom-ui-linter
adom-ui-linter install
```

Or via adompkg:

```bash
adompkg install adom-ui-linter
```

## Usage

```bash
# Lint the current directory (all categories)
adom-ui-linter lint .

# Lint a specific app
adom-ui-linter lint /home/adom/project/adom-step

# Only check header and UI patterns
adom-ui-linter lint . --category header,ui-patterns

# JSON output for programmatic consumption
adom-ui-linter lint . --json

# Only show failures and warnings
adom-ui-linter lint . --failures-only

# List all checks
adom-ui-linter checks

# Health check
adom-ui-linter health
```

## Dependencies

### adompkg (auto-installed)

None. `adom-ui-linter` is a standalone Rust binary with zero runtime dependencies.

### System (manual)

| Dependency | Required | Notes |
|---|---|---|
| Rust toolchain | Build only | `cargo build --release` to compile from source |

## What it encodes

The linter encodes rules from these Adom skills into deterministic checks:

- `adom-app-header` -- header layout, fonts, popover, favicon
- `human-ui-patterns` -- tooltips, toggle state, ALL CAPS, color tokens
- `adom-cli-design` -- output format, subcommands, isatty, hints
- `app-creator` -- AI-drivability, proxy URLs, color palette
- `tool-publisher` -- VERSION sync, release profile, wiki metadata
- `ai-hints-in-clis` -- why Hint: lines matter and how to write them
- `relay-hint-pattern` -- User-Agent gate on relay servers

## Build

```bash
cargo build --release
sudo cp target/release/adom-ui-linter /usr/local/bin/
adom-ui-linter install
```