Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / native-runtime-and-cli

Native runtime and CLI

The Native runtime and CLI are the Rust workspace that turns Impeccable’s product checks and design workflows into one native executable. The workspace shares rule meaning, project context, browser measurement, agent hooks, live editing, skill distribution, account access, and visual composition across local and browser-facing use.

Workspace role

The Rust workspace provides one native engine with clear boundaries between shared rule foundations, execution environments, account state, agent services, and user-facing commands. The impeccable package builds the executable that the skill launcher runs. The other crates provide reusable services for the executable and browser-facing consumers, including agent request handling and trusted bundle support.

The workspace keeps those product crates in one local dependency graph. The manifest names the agent, bundle, MCP, and foundation-scan services alongside the native runtime services, while the lockfile records the resolved graph used by the executable and its supporting tools.

References: Cargo.toml• L4-35 Cargo.lock• L527-580 Cargo.lock• L601-608 Cargo.lock• L711-718 Cargo.lock• L779-790

Shared foundations

The shared foundation defines portable data and browser measurement contracts for rule checks. It also provides common color, page-model, text-rule, CSS-scan, and rule-registry values, so native, browser, snapshot, and WebAssembly paths use the same finding shape and rule meaning.

References: crates/…/lib.rs• L1-11 crates/…/mod.rs• L1-30 crates/…/snapshot.rs• L59-64 crates/…/registry.rs• L12-32 crates/…/lib.rs• L1-13

The common layer supplies the boundary for command execution. A command receives arguments and an Io handle for streams, environment, working directory, and bounded input. It returns an exit code to the top-level executable, which alone controls process exit and stream flushing.

References: crates/…/lib.rs• L1-7 crates/…/lib.rs• L40-85 crates/…/lib.rs• L113-119

Account services

The account crate gives the native runtime a signed-in identity and access to account-backed features. It handles browser sign-in, credential storage, token refresh, sign-out, entitlement checks, public plan text, and optional design-health upload. The workspace makes this service a first-class member, and the CLI uses it before scan dispatch so account state can select the available rule engine. See account and Pro access for the service and entitlement lifecycle.

References: Cargo.toml• L14-28 crates/…/Cargo.toml• L1-34 crates/…/lib.rs• L1-13 crates/…/session.rs• L44-68 crates/…/mod.rs• L1-21 crates/…/health.rs• L1-12

Runtime layers

The workspace separates pure rule work from work that needs a browser or the operating system. This lets the same product behavior serve a local CLI, a browser page, an extension, and restricted WebAssembly hosts.

Rule execution

The rule core contains detector logic and its heuristics. It combines portable rule decisions with adapters for live page facts, captured geometry, painted surfaces, rendered text lines, and source-text patterns. Shared checks decide the meaning of findings, while adapters supply facts that each execution environment can know.

References: crates/…/lib.rs• L1-13 crates/…/driver.rs• L1164-1235 crates/…/page_checks.rs• L237-349 crates/…/quality.rs• L792-831 crates/…/rules.rs• L956-1067

The static HTML engine and browser engine adapt different inputs to the same rule model. Static HTML supports local source scans. The browser engine loads a live page and runs the native rule core over captured page facts. The detector connects these engines through explicit seams.

References: crates/…/lib.rs• L1-11 crates/…/lib.rs• L1-5 crates/…/lib.rs• L1-14

Browser runtime

The browser-facing runtime discovers a Chromium-based browser, drives it through the Chrome DevTools Protocol, and captures page state for detection and visual evidence. It validates scan targets before rule execution and keeps visual and typography findings tied to what a reader can see.

References: crates/…/lib.rs• L1-31 crates/…/lib.rs• L104-128 crates/…/lib.rs• L1134-1177 crates/…/background.rs• L132-160 crates/…/visual.rs• L108-245

The browser path can share one browser process across several URL scans. It also supports evidence capture and replay, so a recorded page can be checked again without opening a browser.

References: crates/…/lib.rs• L130-189 crates/…/lib.rs• L631-674 crates/…/lib.rs• L692-743

Browser page model

The browser page model gives the rule core one view of a page whether rules run beside the live DOM or against a serialized snapshot. The snapshot preserves the structure, styles, geometry, media state, animation state, rendered text lines, and linked stylesheet input needed for the same rule decisions. Missing capture facts remain unknown instead of being guessed.

References: crates/…/dom.rs• L181-252 crates/…/snapshot.rs• L59-64 crates/…/snapshot.rs• L329-341 crates/…/detect-antipatterns-browser.js• L490-560

WebAssembly runtime

The WebAssembly crate exposes the browser rule surface as JSON-in and JSON-out functions. A page or extension supplies the DOM bridge, while the compiled rule core supplies findings and the registry. Optional exports support pure rule calls and file-oriented detection where a native binary is not available.

References: crates/…/lib.rs• L1-19 crates/…/lib.rs• L41-75 crates/…/Cargo.toml• L11-24

The workspace bundling task turns the WebAssembly runtime and its JavaScript page support into assets for live mode and extension consumers. It also checks tracked assets for drift before they are used.

References: crates/…/main.rs• L1-30 crates/…/main.rs• L60-119 crates/…/detect-antipatterns-browser.js• L1-10

Command orchestration

The native executable is a thin command router. It first gives scan-shaped invocations to the account-aware Pro dispatcher, then maps the first argument to a domain command, passes the remaining arguments and shared Io context to that command, and turns the returned status into the process result.

CLI dispatch

The top-level router handles help, version, engine probing, detection, skills, context, hooks, live mode, account commands, and component-fidelity commands. It preserves path-shaped shorthand for detection and keeps aliases at the command boundary. The launcher can identify this engine before it starts a real command. See CLI dispatch and runtime for the command contract and detailed dispatch flow.

Agent-facing protocol services use the same native command boundary to connect agent requests with project checks and design actions. See agent protocol services for their service-level flow.

References: crates/…/main.rs• L1-29 crates/…/lib.rs• L1-18 crates/…/main.rs• L14-28

The command groups keep their own workflow rules behind the router. Context commands resolve project inputs and maintain design records. Skills commands install and update the agent-facing skill bundle. Hook commands connect editor events to design checks. Live commands manage an interactive project session. Account commands manage sign-in and access state. Composition commands coordinate reference comparison and build progress.

References: crates/…/lib.rs• L1-3 crates/…/lib.rs• L15-55 crates/…/lib.rs• L1-3 crates/…/lib.rs• L1-21 crates/…/lib.rs• L1-5 crates/…/lib.rs• L153-253 crates/…/main.rs• L57-104

When a user invokes the native executable, the main flow is:

flowchart LR
    A[Launcher or terminal] --> B[Native executable]
    B --> C{Scan or command}
    C --> D[Account-aware Pro dispatch]
    D --> E[Pro engine or open engine]
    C --> F[Context, account, or skill command]
    C --> G[Hook or live workflow]
    C --> H[Component-fidelity operation]
    E --> I[Static HTML or browser engine]
    I --> J[Findings and evidence]

References: crates/…/main.rs• L14-28 crates/…/mod.rs• L763-809 crates/…/lib.rs• L26-44 crates/…/lib.rs• L59-91

Detection orchestration

The detector owns input classification and command-level scan behavior. It chooses the static HTML engine for local markup and the native browser engine for URLs through explicit seams. The command layer therefore presents one detection interface while the execution environment changes.

References: crates/…/lib.rs• L1-11 crates/…/lib.rs• L32-56 crates/…/main.rs• L57-58 crates/…/main.rs• L123-145

Account and Pro access

Account commands establish the session that account-backed services use. Login uses a browser-based OAuth flow and stores credentials in a platform-appropriate private backend. Later calls refresh tokens under a shared lifecycle lock, while whoami combines live entitlement with optional public plan information. See account and Pro access for the service-level flow.

Pro access is a signed engine choice layered around scan execution. A signed-in, entitled machine can use a separately built rule engine after the local dispatcher verifies its release manifest, lease, sign-in binding, and artifact digest. If any check fails, the open engine remains the safe fallback.

References: crates/…/oauth.rs• L1-5 crates/…/store.rs• L1-15 crates/…/session.rs• L75-184 crates/…/lib.rs• L251-337 crates/…/mod.rs• L13-21 crates/…/mod.rs• L696-809

Design context

The context layer turns project material into information that other design workflows can use. Its commands resolve product and design records, surface briefs, critique history, concept seeds, generated images, questions, and drift reports. It also checks whether project artifacts and hook wiring remain usable. See design context and critique for that workflow.

Native image generation turns a prompt or prompt file into a design asset for a context or composition workflow. It supports new images and reference-based edits, records the generation choice beside the output, and can use a deterministic local mode when an API call is not wanted. A remote reference must return image data before generation continues.

References: crates/…/generate_image.rs• L315-379 crates/…/generate_image.rs• L381-545 crates/…/lib.rs• L15-55 crates/…/context_cli.rs• L700-835 crates/…/doctor.rs• L34-45 crates/…/hook_wiring.rs• L61-145 crates/…/main.rs• L62-75

Component composition

The component-fidelity path compares a built page with a design reference and coordinates the work needed to assess visual fidelity. The build-phase command moves a project through gates for comps, measured regions, raster plates, hero fidelity, page sections, motion, responsive behavior, and final review. Pure comparison work stays separate from the renderer that supplies page evidence. See component composition operations for the operation-level flow.

References: crates/…/lib.rs• L1-14 crates/…/lib.rs• L1-15 crates/…/build_phase.rs• L1-35 crates/…/build_phase.rs• L147-160 crates/…/main.rs• L75-99

Design seed generation

Seed generation uses shared native plumbing to create stable design references for later context and composition work. A seed reference lets a later roll or build point back to the same design choice without exposing the local seed key. See design seed generation for the seed lifecycle.

References: crates/…/Cargo.toml• L8-16 crates/…/Cargo.toml• L16-21 crates/…/Cargo.toml• L14-23 crates/…/serve_question.rs• L447-580

Design foundations and taste

Design foundation and taste workflows establish reusable direction that later seed, context, and composition operations can apply to a target project. They connect high-level design choices to the native command and agent surfaces instead of treating each workflow as an isolated output. See design foundations and taste workflows for the service-level flow.

References: crates/…/Cargo.toml• L8-16 crates/…/lib.rs• L15-55 crates/…/lib.rs• L1-14 crates/…/main.rs• L57-104

Skill distribution

The skills command distributes the agent-facing rules, commands, hooks, and helper agents that use this native engine. It obtains a versioned bundle, checks its trust and size boundaries, stages it before installation, and compares installed files by normalized content so provider paths do not create false drift.

Remote bundle transfers use bounded reads and idle timeouts. Archive extraction stays inside the staging area and rejects unsafe paths, oversized entries, and suspicious compression, while a failed update removes its incomplete staging state.

References: crates/…/bundle.rs• L151-255 crates/…/bundle.rs• L257-353 crates/…/bundle.rs• L355-430 crates/…/bundle.rs• L496-552 crates/…/bundle.rs• L580-646 crates/…/Cargo.toml• L8-20

Agent hook workflow

The agent hook workflow feeds design findings back into the harness that made an edit. A post-edit pass gives fast feedback, while a Stop or completion pass reviews the wider session and unfinished build work. The workflow uses a verified first edit preimage to label findings as new, pre-existing, or unknown instead of treating all visible debt as a regression. See agent hook workflow for the event-level flow.

The hook keeps bounded session state for finding de-duplication and attribution. Disposable cache state can move to a machine-level cache root while user-authored project configuration stays with the project. Stop attribution remains unknown for HTML or dependency-sensitive findings and for stale or malformed baselines.

References: crates/…/lib.rs• L40-67 crates/…/hook_lib.rs• L145-205 crates/…/hook_lib.rs• L587-663 crates/…/hook_lib.rs• L678-777 crates/…/stop_baseline.rs• L1-18 crates/…/stop_baseline.rs• L70-175 crates/…/stop_baseline.rs• L210-243 crates/…/hook_wiring.rs• L61-145

Live editing runtime

The live editing runtime connects a browser session to source files without assuming one web framework. It selects a framework adapter, finds the source element, creates a variant or insert session, and returns the source and style contract that the agent must follow. Accept and discard then make the selected variant permanent or restore the prior source, with receipts and source locks preventing conflicting repeats. See live editing sessions for the session lifecycle.

References: crates/…/mod.rs• L1-31 crates/…/mod.rs• L75-117 crates/…/wrap_common.rs• L484-605 crates/…/live_wrap.rs• L209-484 crates/…/live_insert.rs• L210-330 crates/…/live_accept.rs• L184-269

Runtime boundaries

The most important system boundary is whether a path can use native operating-system services. Pure rule and composition logic stays portable. Native adapters add browser, file, process, network, account, and session behavior only where the product flow needs it.

Native adapters

The CLI adds native adapters for capture and font rendering. These adapters let composition commands use browser-backed evidence without placing browser dependencies inside the pure composition layer. Reviewed captures remain evidence for a current visual state. They do not replace native integrity and fidelity checks.

References: crates/…/lib.rs• L1-12 crates/…/main.rs• L75-99 crates/…/main.rs• L123-145

Project runtime state

Design rounds, critique snapshots, questions, captures, and build state are local runtime records. The workspace keeps these records out of normal commits where possible, while preserving hand-edited project records such as shared critique ignore files. Git layout support covers normal repositories, linked worktrees, and submodules without spawning Git for each guarded write.

References: crates/…/git.rs• L1-17 crates/…/git.rs• L19-84 crates/…/critique_storage.rs• L441-508 crates/…/serve_question.rs• L447-580 crates/…/build_phase.rs• L147-160

Account state

Account state joins local credentials to a remote issuer without making the rest of the runtime depend on token details. The service keeps sign-in state separate per account origin, binds stored secrets to the selected backend, and uses generation changes to order login, logout, token refresh, and Pro lease updates. Design-health sync is an optional downstream report and does not change scan output or its exit code.

References: crates/…/config.rs• L13-48 crates/…/store.rs• L27-53 crates/…/store.rs• L151-165 crates/…/health.rs• L1-12 crates/…/health.rs• L89-145

Generated assets

Changes to the rule core, foundation, WebAssembly exports, or browser bundle can change generated browser and extension assets. The workspace task rebuilds those outputs and provides a check mode that detects stale tracked assets. The generated live asset must keep its measurement contract aligned with both the Rust snapshot consumer and browser bundle.

References: crates/…/main.rs• L26-30 crates/…/main.rs• L77-119 crates/…/snapshot.rs• L59-64 crates/…/detect-antipatterns-browser.js• L520-560

Change checklist

When these files or sections are changed, remember to consider these:

  • Changing crates/core or crates/foundation can require refreshed live and extension detector assets through cargo xtask bundle.
  • Changing the workspace members or shared dependency aliases in Cargo.toml must keep the native binary, account crate, agent services, MCP boundary, foundation scanner, bundle tooling, and lockfile in one resolvable graph.
  • Changing Cargo.lock after a workspace dependency update must preserve the package links and resolved versions used by the native executable and its supporting services.
  • Changing command names or aliases in crates/…/main.rs must stay aligned with command-group entry points, account dispatch, and launcher verb names.
  • Changing account service endpoints, OAuth scopes, token storage, or entitlement fields must preserve the account issuer boundary and the Pro sign-in binding.
  • Changing detector engine seams must preserve the distinction between static HTML scans and browser URL scans.
  • Changing browser capture fields, rendered-text measurements, linked stylesheet input, or style-property lists must keep the Rust consumer and generated JavaScript capture contract synchronized.
  • Changing context target resolution, surface-brief identity, or critique target identity must preserve safe behavior for monorepos, URLs, long paths, and legacy records.
  • Changing image generation request or sidecar fields must keep prompt provenance, reference handling, output format, and decision-page slot recording aligned.
  • Changing hook manifests must keep the writer, context coverage check, doctor report, and stale-hook repair in agreement across provider and user scopes.
  • Changing hook cache location or session attribution must preserve cache lookup across project roots and the distinction between verified pre-existing findings, new findings, and unknown findings.
  • Changing live framework traits must keep source search, wrapper creation, accept, discard, and CSS authoring contracts aligned.
  • Changing composition state or gate inputs must keep receipts tied to the current reference, region, asset, and build state.
  • Changing WebAssembly features or bundle inputs can alter the browser assets received by live and extension consumers.
  • Changing bundle download or extraction limits must preserve signed-release verification, staging cleanup, and path confinement.

Important failure modes

TriggerConsequenceGuard
A browser cannot be found or launchedURL scans fail instead of producing page findingsBrowser discovery and launch errors return through the URL engine.
A live capture and snapshot consumer use different page factsBrowser and extension paths can produce different findingsKeep the capture contract synchronized and report missing facts as unknown.
A command verb is not routed by the native executableThe command returns an unknown-command error and exit code 1Keep top-level dispatch and command-group entry points aligned.
A sign-in callback has the wrong issuer or stateLogin does not save credentialsThe loopback OAuth flow checks PKCE, state, and issuer before exchange.
A credential store or account state changes during login, logout, or refreshA newer sign-in can be overwritten or a revoked sign-in can returnThe lifecycle lock and generation-tied tombstone order every write.
A Pro manifest, lease, or artifact fails verificationThe open engine runs instead of the Pro engineVerify the pinned release signature, lease, sign-in, revision, and artifact digest on dispatch.
A hook manifest names a missing or old launcherEditor changes run no hook, while context can report false coverageShared marker checks and manifest repair distinguish current launcher entries from old entries.
A Stop event has no verified first-edit preimage or uses a stale baselineExisting debt can be mislabeled as a new regressionKeep attribution unknown until the native hook verifies the edit result and baseline version.
A target identity or snapshot slug is ambiguousCritique history can be read or closed for the wrong targetBind records to resolved file or URL identity and refuse ambiguous matches.
A live element is generated, ambiguous, or unclosedThe runtime refuses to write a wrapper and returns an agent-driven fallbackKeep generated-file checks and source range resolution conservative.
A build reference, plate, or measured region changes after approvalA later gate rejects stale evidence instead of silently reusing itRevalidate receipts against current file, reference, region, and comp hashes.
A remote image reference is missing, too large, or not an imageImage generation stops without writing a generated outputValidate the response status, byte limit, and image signature before the API request.
Generated detector assets do not match current runtime sourcesLive mode or extension consumers run stale rule behaviorcargo xtask bundle --check compares tracked assets with a fresh build.
A bundle is oversized, unsigned, or unsafe to extractInstallation stops before accepting untrusted or dangerous contentDownload, signature, archive-size, compression-ratio, and path-confinement checks guard staging.

Key files

FileWhy to read it
Cargo.tomlDefines the workspace, shared crate aliases, and native build profile.
Cargo.lockPins the workspace dependency graph so native, agent, account, browser, and bundle paths resolve together.
crates/…/main.rsShows the native executable’s account-aware command boundary and exit handling.
crates/…/lib.rsShows the embeddable router and native browser adapters exposed to downstream binaries.
crates/…/lib.rsDefines the shared command input, output, environment, and exit-code boundary.
crates/…/git.rsDefines how local runtime output is kept out of commits and how linked worktrees are handled.
crates/…/lib.rsExplains the portable data and helper layer used by rule checks.
crates/…/dom.rsDefines the browser measurement surface shared by live, snapshot, and test DOMs.
crates/…/snapshot.rsDefines the page snapshot contract for replayed browser rules.
crates/…/lib.rsShows where detector rule behavior sits and where native services stop.
crates/…/lib.rsDefines detector orchestration and engine seams.
crates/…/lib.rsShows how URL scans use a native browser and produce findings or evidence.
crates/…/lib.rsShows the browser and extension-facing WebAssembly surface.
crates/agentsDefines the native services used by external agent clients.
crates/mcpDefines the MCP-facing service package in the native dependency graph.
crates/foundations-scanDefines the foundation-scan package in the native dependency graph.
crates/…/lib.rsDefines account commands and the high-level sign-in, sign-out, and identity flow.
crates/…/oauth.rsShows how browser sign-in returns a verified native-app authorization result.
crates/…/store.rsDefines private credential storage and lifecycle ordering.
crates/…/mod.rsDefines Pro refresh, offline verification, and scan dispatch fallback.
crates/…/health.rsShows the optional, non-blocking design-health upload boundary.
crates/…/context_cli.rsShows how project context becomes bounded agent directives.
crates/…/generate_image.rsShows how prompts and reference images become recorded design assets.
crates/…/doctor.rsShows how artifact drift becomes a report or safe mechanical fix.
crates/…/critique_storage.rsShows how critique history is tied to target identity and freshness.
crates/…/serve_question.rsShows how design decisions and concept rolls bind to one local question round.
crates/…/hook_wiring.rsDefines the current provider hook contracts.
crates/…/lib.rsDefines the browser-independent composition and fidelity foundation.
crates/…/build_phase.rsShows how visual build work advances through persisted gates.
crates/…/lib.rsShows the native hook entry points and their shared runtime.
crates/…/hook_lib.rsShows session state, finding filtering, attribution support, and bounded feedback.
crates/…/stop_baseline.rsExplains conservative attribution at the end of an agent session.
crates/…/bundle.rsDefines trusted bundle download, staging, extraction, and freshness checks.
crates/…/hook_manifest.rsDefines provider hook installation, migration, merge, and repair.
crates/…/mod.rsDefines framework selection and source/style traits for live editing.
crates/…/wrap_common.rsDefines source element search and the wrapper authoring contract.
crates/…/live_wrap.rsShows how a source element becomes a variant session.
crates/…/live_insert.rsShows how an insert session is placed around an existing source anchor.
crates/…/live_accept.rsShows how a variant is accepted, discarded, or made permanent.
crates/…/detect-antipatterns-browser.jsShows the generated browser measurement surface used by live and extension paths.
crates/…/main.rsDefines how browser and extension assets are built and checked.