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 / rust-cli-runtime

Rust CLI runtime

The Rust CLI runtime is the native command entrypoint for Impeccable. It turns one process invocation into a routed workflow that can inspect projects, run design checks, assess project foundations, manage account and health state, report setup and critique state, install or connect the Loop app, control agent design switches, perform component and visual work, create walkthrough evidence, and exchange capture evidence with a host. It is the native layer below the native runtime and CLI page and connects to agent protocol services, account and Pro services, design seed generation, and component composition operations.

Runtime boundary

The runtime keeps process concerns at the edge. Command crates receive a shared command context and return a status code, while capability crates perform detection, browser work, account work, review work, or project changes.

flowchart LR
    A[CLI process] --> B[Argument and verb dispatch]
    B --> C[Shared Io context]
    C --> D[Command workflows]
    D --> E[Rule and data core]
    D --> F[HTML or browser engines]
    D --> G[Account, project, hook, live, review, and Loop services]
    E --> H[Findings, evidence, files, and exit status]
    F --> H
    G --> H

The main binary owns the final process actions. It collects the arguments, creates the shared I/O context, gives eligible scans to the verified Pro dispatcher, otherwise invokes the open router, flushes both output streams, and exits with the chosen code. Normal commands can also schedule detached setup and taste reports without delaying the command; hook paths do not schedule them. This gives direct runs and embedded callers a clear process contract. crates/…/main.rs• L14-34, crates/…/router.rs• L30-48, crates/…/setup_report.rs• L7-23

Command entrypoint

Process boundary

The native executable is the single process boundary for the command surface. It passes process arguments and standard streams to the embeddable router, which handles help, version, probe, unknown-command, account, setup, critique, Loop, foundation, walkthrough, switch, visual, and shorthand cases beside the domain workflows. crates/…/main.rs• L14-34, crates/…/router.rs• L20-136, crates/…/router.rs• L185-263

This boundary also connects installed launchers to the engine. The probe verb lets a launcher distinguish this native engine from an older command-line program without adding probe output to user help. Browser extension startup enters through the native-messaging host boundary rather than through scan dispatch. crates/…/router.rs• L26-29, crates/…/router.rs• L64-71

References: crates/…/main.rs• L14-34 crates/…/router.rs• L20-71

Command dispatch

The dispatcher maps stable command names to domain workflows. Aliases remain at this layer, so each workflow has one internal route even when users or launchers use more than one spelling. crates/…/router.rs• L20-263

Command groupPurposeOwning workflow
detect, ignoresFind design issues in local targets or URLs and manage detector exclusionsimpeccable-detect
foundationsCheck the project roadmap items that local files and scans can proveNative foundation workflow
login, logout, whoami, health, setup, critiquesManage account access, design-health state, setup reporting, and critique reportingimpeccable-account
status, switches, switches-refreshInspect and synchronize design instructions used by installed agentsAccount setup and native agent-block workflows
skills, help, install, link, update, checkManage the installed skill and its launcher integrationimpeccable-skills
loopInstall, update, connect, or disconnect the optional macOS Loop appNative CLI adapter
walkthroughTurn a recording into a walkthrough film, poster, and post dataNative media adapter
agents, mcpRun agent-facing services and presence or protocol workflowsimpeccable-agents and impeccable-mcp
Context verbsBuild and inspect project context used by design workflowsimpeccable-context
comp-spec, comp-diff, font-match, build-phase, first-viewport, shotSpecify, compare, inspect, and gate visual fidelity workimpeccable-comp-verbs and native visual adapters
hook, hook-before-edit, hooksRun edit checks, pre-edit gates, and hook administrationimpeccable-hook
live*Start and control the live design workflowimpeccable-live
component-review, capture-server, motion-captureProduce review previews and connect native capture to host workflowsCLI adapters and context review services

The router also recognizes scan verbs before path shorthand. A path-shaped argument can enter detection without an explicit detect verb, while a named command remains a command even when a same-named path exists in the working directory. An unrecognized non-target remains an error. crates/…/router.rs• L249-263, crates/…/router.rs• L490-576

References: crates/…/router.rs• L20-263 crates/…/router.rs• L490-576

Pro dispatch boundary

The open binary treats rule scans as a special integration boundary. detect, path-shaped scans, and hook scans may be handed to a verified Pro build, but account, health, setup, critique, Loop, context, foundation, walkthrough, switch, and other service commands stay in the open binary. After a Pro scan dispatch, the open binary may schedule a silent setup report, except for edit hooks. crates/…/main.rs• L17-29, crates/…/router.rs• L267-300, crates/…/router.rs• L490-506, crates/…/setup_report.rs• L7-23

The boundary prevents a Pro child from dispatching back into another Pro child. It also keeps scan behavior unchanged for users who are not signed in or for runs that set the child or dispatch guard state. crates/…/pro_dispatch.rs• L34-100

References: crates/…/main.rs• L17-29 crates/…/router.rs• L267-300 crates/…/router.rs• L490-506 crates/…/pro_dispatch.rs• L34-100

Shared command context

I/O contract

The shared Io context gives each workflow controlled access to standard output, standard error, lazy standard input, the process environment, the current directory, and home-directory lookup. A command returns an exit code instead of ending the process itself, which keeps the workflow usable from tests and from other runtime boundaries. crates/…/lib.rs• L1-7

Input is read only when a command needs it and is bounded to protect hook and server paths from an unbounded pipe. Output stays with the caller until the main binary flushes the streams. crates/…/lib.rs• L37-44

References: crates/…/lib.rs• L1-7 crates/…/lib.rs• L37-44 crates/…/lib.rs• L46-116

Rule core

The shared rule core turns plain page, DOM, style, and browser facts into findings. The foundation supplies the common data types, rule registry, browser probe boundary, and language behavior that the checks need. Neither layer owns files, processes, or network access, so native adapters can feed the same rule model from static HTML, a browser page, a saved capture, or WebAssembly. crates/…/lib.rs• L1-13, crates/…/lib.rs• L1-11

The browser side adds a render-aware layer to this boundary. It combines element checks, page checks, quality checks, paint checks, text geometry, and visual layer checks so a finding reflects what a visitor can see rather than only what a stylesheet declares. The native driver keeps these checks in one collection pass and applies shared ignore, disabled-rule, paint, and page-level handling. crates/…/mod.rs• L13-72, crates/…/driver.rs• L2627-2755

The core also shares rule decisions between static and rendered scans. Pure checks cover patterns such as borders, color use, contrast, gradients, and typography, while browser adapters supply computed style and layout facts. Per-page handling can group repeated findings without changing the meaning of the underlying rule. crates/…/rules.rs• L345-467, crates/…/rules.rs• L969-1078, crates/…/rules.rs• L1467-1553

This separation is the main shared-core boundary. Command workflows decide how to obtain and present facts, while the rule core decides what those facts mean. It supports consistent findings across local scans, browser scans, replay, and other hosts without giving rule code direct access to the operating system.

References: crates/…/lib.rs• L1-26 crates/…/lib.rs• L1-30 crates/…/mod.rs• L13-104 crates/…/driver.rs• L2627-2870 crates/…/mod.rs• L1-65 crates/…/rules.rs• L345-467 crates/…/rules.rs• L969-1078 crates/…/rules.rs• L1467-1553

Common services

The common crate supplies the small process services that command workflows need but the rule core must not know about. These services cover environment normalization, bounded input, path and JSON helpers, Git repository and runtime-state handling, child-process behavior, interruption, and platform-neutral command launch behavior. crates/…/lib.rs• L20-35, crates/…/proc.rs• L1-7

These services form a compatibility layer around operating-system differences. For example, live and review servers can test process liveness and respond to interrupts through one shared contract instead of each command inventing its own platform rules. crates/…/proc.rs• L62-91, crates/…/proc.rs• L136-188

Git helpers resolve repository metadata from disk without starting Git. They support normal checkouts and linked worktrees while keeping submodule and separate-Git-directory layouts distinct. Runtime output helpers add local ignore rules for generated mocks and review data without replacing user entries, so repeated command runs do not pollute commits. crates/…/git.rs• L1-84

References: crates/…/lib.rs• L20-116 crates/…/proc.rs• L62-133 crates/…/proc.rs• L136-188 crates/…/git.rs• L1-84

Capability boundaries

Detection engines

Detection is an orchestration layer with two engine boundaries: one for static HTML and one for URLs in a browser. The detection crate defines those contracts without depending on either concrete engine. The CLI supplies both the static HTML engine and a process-environment-backed browser engine when it builds the runtime. crates/…/engines.rs• L1-4, crates/…/router.rs• L11-19, crates/…/router.rs• L578-586

The static path reads local HTML through the HTML engine. The URL path uses the browser engine that discovers and controls a Chromium-based browser, then passes captured page facts to the shared rule core. A multi-URL run can keep one browser session while still giving each target its own page scan. The browser core turns those facts into grouped element findings and page findings, then the detection workflow presents them to the command boundary. crates/…/lib.rs• L1-5, crates/…/lib.rs• L1-16, crates/…/engines.rs• L65-112, crates/…/driver.rs• L2627-2870

References: crates/…/engines.rs• L1-112 crates/…/router.rs• L11-19 crates/…/router.rs• L578-586 crates/…/lib.rs• L1-5 crates/…/lib.rs• L1-16

Foundations checks

The foundations command turns a project health roadmap into evidence-based states. It combines local file checks with selected detector findings, then shows which items fail, which are checked, and which still lack enough evidence. An item with no proof remains unchecked rather than becoming a false pass. crates/…/foundations.rs• L1-5, crates/…/foundations.rs• L12-105, crates/…/foundations.rs• L244-266

The roadmap covers early project needs such as secrets, contrast, error pages, icons, social previews, runnable documentation, tests, dependency safety, error tracking, migrations, and infrastructure. The command can return a human roadmap or JSON for an agent. A full detector run can also pass the foundation states into the same optional account health report used by detect, without changing local command output. crates/…/foundations.rs• L254-275, crates/…/router.rs• L267-300

Foundation evidence is conservative. It is uploaded only with the required consent and repository boundary, and detector passes are withheld when the scan cannot judge all relevant files or when advisory findings remain unresolved. This keeps “checked” distinct from “not enough evidence.” crates/…/foundations.rs• L107-192

References: crates/…/foundations.rs• L1-5 crates/…/foundations.rs• L12-105 crates/…/foundations.rs• L107-192 crates/…/foundations.rs• L195-275 crates/…/router.rs• L267-300

First-viewport checks

The first-viewport command gives a build a repeatable check of the first screen at mobile and desktop sizes. It loads a URL or local page in a real browser and checks whether the stated thesis is visible, the primary action is wholly usable, figures are marked when they are supplied by the design, the page responds to the action, and the page does not contain an excessive empty band. crates/…/first_viewport.rs• L1-14, crates/…/first_viewport.rs• L277-385

The command uses 390×844 and 1440×900 by default, with optional viewports for other review targets. It can also save full-page captures with stable mobile and desktop names. A failed browser launch, page load, selector match, visual measure, or action response returns a failing exit code so the check can gate the build. crates/…/first_viewport.rs• L23-31, crates/…/first_viewport.rs• L387-479

The following flow shows how a page becomes a viewport result and optional review evidence.

flowchart LR
    A[URL or local page] --> B[Load at viewport]
    B --> C[Measure thesis and action]
    C --> D[Check figures and empty space]
    D --> E[Exercise primary action]
    E --> F[Optional full-page capture]
    F --> G[Lines and exit status]

References: crates/…/router.rs• L185-199 crates/…/first_viewport.rs• L1-31 crates/…/first_viewport.rs• L267-385 crates/…/first_viewport.rs• L387-479

Agent instruction switches

Agent instruction switches give a person one controlled way to turn Impeccable guidance on or off for the agents installed on the machine. The CLI reports the catalog for the settings service and writes only its own marked block in each supported agent rule file; the person's surrounding rules remain outside that block. crates/…/agent_block.rs• L1-7, crates/…/agent_block.rs• L21-34, crates/…/agent_block.rs• L494-515

The same switch model spans agents that read user-level rule files and Cursor, which keeps its personal rule in a local repository rule. The runtime preserves symlinks, avoids taking over tracked team files, retains unknown newer switch lines, and serializes concurrent read-modify-write operations. A prior taste-only block is recognized and folded into the shared block on the next write. crates/…/agent_block.rs• L86-102, crates/…/agent_block.rs• L134-172, crates/…/agent_block.rs• L339-405

This boundary keeps settings policy outside the command router. The router exposes status and switch commands, while the agent-block service owns the file contract and returns errors before it changes a file when its markers are unsafe. crates/…/router.rs• L94-118, crates/…/agent_block.rs• L54-72, crates/…/agent_block.rs• L251-336

References: crates/…/agent_block.rs• L1-7 crates/…/agent_block.rs• L21-34 crates/…/agent_block.rs• L54-172 crates/…/agent_block.rs• L231-336 crates/…/agent_block.rs• L339-440 crates/…/router.rs• L94-118

Walkthrough conversion

The walkthrough command turns a browser recording into the media package expected by a Needs you walkthrough card. It accepts common recording formats and produces a browser-ready H.264 film without audio, a poster image, chapter data, and JSON post fields that describe the two attachments. crates/…/walkthrough.rs• L1-20, crates/…/walkthrough.rs• L642-679

The workflow uses the host's ffmpeg and ffprobe tools as an external media boundary. It checks the source before conversion, validates the finished film, and reports machine-readable errors when the tools or recording do not meet the card contract. The result stays local until an agent uses the returned paths and metadata with the host service. crates/…/walkthrough.rs• L104-166, crates/…/walkthrough.rs• L304-327, crates/…/walkthrough.rs• L514-543

The card contract keeps the evidence small and readable:

Media concernContract
FilmUp to two minutes and 50 MB
ChaptersUp to 12 ordered moments with short one-line labels
PosterA still taken from the finished film
OutputOne JSON object with paths, sizes, hashes, and post instructions

The command writes the film and poster as one output pair. It protects existing named files and removes partial output when conversion or placement fails, so a caller does not receive metadata for a missing or mismatched attachment. crates/…/walkthrough.rs• L279-301, crates/…/walkthrough.rs• L365-443, crates/…/walkthrough.rs• L618-679

The following flow shows how a recording becomes local evidence that an agent can send to the Needs you service.

flowchart LR
    A[Browser recording] --> B[Probe source]
    B --> C[Encode film]
    C --> D[Validate film]
    D --> E[Cut poster]
    E --> F[Hash and place output pair]
    F --> G[JSON post fields]

References: crates/…/router.rs• L119 crates/…/walkthrough.rs• L1-20 crates/…/walkthrough.rs• L220-327 crates/…/walkthrough.rs• L350-679 crates/…/walkthrough.rs• L783-835

Account and health services

Account commands connect the local CLI to the account service without moving account policy into the router. Login, logout, identity display, health sync, setup reporting, and critique reporting remain ordinary commands or optional follow-ups to local work. crates/…/router.rs• L77-118, crates/…/account.rs• L20-139

When health sync is wanted, detection first produces its normal findings. The runtime then sends a separate scan report with repository-level identity and ruleset data. The foundations command can add its evidence map to that report. This follow-up does not change detection output or its exit code, and it does not run for partial scans, hooks, opt-out environments, or unavailable health access. crates/…/router.rs• L267-300, crates/…/foundations.rs• L267-275, crates/…/health.rs• L105-175, crates/…/health.rs• L177-227

The account boundary also protects local command use from service state. The CLI can report plan data when the plan catalog is available or use a local entitlement fallback when it is not. Token refresh and service locks must not turn an ordinary scan into a long wait or break an existing sign-in. crates/…/account.rs• L51-139, crates/…/health.rs• L272-359

The following flow shows how scan results and account state meet without making the account service part of the rule scan itself.

sequenceDiagram
    participant User
    participant CLI
    participant Detector
    participant Account
    participant Health
    User->>CLI: detect target
    CLI->>Detector: run scan
    Detector-->>CLI: findings and exit code
    CLI->>Account: check local health choice
    alt full scan and sync allowed
        CLI->>Health: upload summary
        Health-->>CLI: accepted or unavailable
    end
    CLI-->>User: original findings and exit code

References: crates/…/router.rs• L77-118 crates/…/router.rs• L267-300 crates/…/foundations.rs• L267-275 crates/…/account.rs• L20-139 crates/…/health.rs• L105-175 crates/…/health.rs• L177-359

Setup reporting

Setup reporting records a small view of the local agent and skill state for an account. Normal explicit commands schedule the report in a detached worker, so a network wait or a slow agent probe does not hold the user-facing command open. crates/…/setup_report.rs• L7-23, crates/…/setup_report.rs• L78-127

The worker invokes the agent inventory command with a bounded process lifetime and temporary file output. It reports only after the local setup feature is enabled, and it does not run from hooks or recurse through its own report command. crates/…/setup_report.rs• L1-23, crates/…/setup_report.rs• L130-216, crates/…/setup.rs• L34-86

References: crates/…/setup_report.rs• L1-23 crates/…/setup_report.rs• L78-216 crates/…/setup.rs• L34-86

Critique reporting

Critique reporting connects a saved local review report to the account service without making upload success part of local report creation. The CLI stores and reads the report locally, applies the user's sync choice, and uploads only new eligible reports when the account grants the required capability. crates/…/router.rs• L151-173, crates/…/critiques.rs• L66-180

The boundary keeps local review work useful when the service is unavailable, the sign-in is stale, the input is unsafe or too large, or the user turns sync off. Disable and forget operations coordinate with an admitted upload so a late response cannot restore a setting that the user turned off. crates/…/critiques.rs• L118-155, crates/…/critiques.rs• L269-305, crates/…/critiques.rs• L378-447

References: crates/…/router.rs• L151-173 crates/…/critiques.rs• L66-180 crates/…/critiques.rs• L118-155 crates/…/critiques.rs• L269-305 crates/…/critiques.rs• L378-447

Loop services

The loop command is a native integration boundary for the optional Impeccable Loop app and its coding-agent connections. It supports install and update on macOS, then can connect or disconnect Loop from supported agent harnesses without taking ownership of the agents' sign-in tokens. crates/…/router.rs• L116-119, crates/…/loop_install.rs• L13-16, crates/…/loop_connect.rs• L1-13

Loop installation

The installer selects a release from checksums embedded in the engine and places the verified app in the user Applications directory. The release is untrusted input until its URL, size, checksum, bundle identity, and version pass validation. crates/…/loop_install.rs• L13-16, crates/…/loop_install.rs• L59-137, crates/…/loop-checksums.txt• L1-5

It stages the app before replacing an existing copy, refuses to update a running app that does not quit, and restores the prior app if the swap fails. Help and argument errors remain usable on every host, while real Loop work fails clearly on non-macOS systems. crates/…/loop_install.rs• L20-26, crates/…/loop_install.rs• L249-285, crates/…/loop_install.rs• L288-443, crates/…/loop_install.rs• L3-87

References: crates/…/router.rs• L116-119 crates/…/loop_install.rs• L13-16 crates/…/loop_install.rs• L20-26 crates/…/loop_install.rs• L59-137 crates/…/loop_install.rs• L249-285 crates/…/loop_install.rs• L288-443 crates/…/loop-checksums.txt• L1-5 crates/…/loop_install.rs• L3-87

Agent connection

Loop connection links Claude Code and Codex to the fixed Impeccable MCP service and installs Loop's hooks through the agent service. It records the exact agent account and files it changed, so disconnect can stop Loop waking and undo only the hooks that this connection owns. crates/…/loop_connect.rs• L1-13, crates/…/loop_connect.rs• L97-149, crates/…/loop_connect.rs• L271-364

Agent guidance now uses one marked Impeccable block in each supported user-level rule file. The block carries the enabled catalog switches, including taste guidance and Loop input guidance, while preserving the person's rules and any lines from a newer engine. A prior taste-only block is migrated into this shared block rather than left beside it. crates/…/agent_block.rs• L1-7, crates/…/agent_block.rs• L21-41, crates/…/agent_block.rs• L134-172

The connection keeps an existing MCP entry intact and never removes an MCP server during disconnect. It reports the exact manual removal command instead. A failed or interrupted connection rolls back its own hook changes, while a changed file remains protected from automatic overwrite. crates/…/loop_connect.rs• L146-269, crates/…/loop_connect.rs• L271-377, crates/…/loop_connect.rs• L142-288, crates/…/loop_connect.rs• L478-587

The boundary also handles multiple agent accounts and missing agent CLIs from recorded state rather than from the current shell alone. It serializes connect and disconnect and protects its private support files before writing them. crates/…/loop_connect.rs• L271-364, crates/…/loop_connect.rs• L394-479, crates/…/loop_connect.rs• L304-346, crates/…/loop_connect.rs• L348-372

References: crates/…/loop_connect.rs• L1-13 crates/…/loop_connect.rs• L97-269 crates/…/loop_connect.rs• L271-479 crates/…/agent_block.rs• L1-7 crates/…/agent_block.rs• L21-172 crates/…/loop_connect.rs• L124-288 crates/…/loop_connect.rs• L304-372 crates/…/loop_connect.rs• L478-587

Change checklist

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

  • Keep every named router verb in step with run, is_scan, and KNOWN_VERBS; a missing name can send a path or command to the wrong engine.
  • Keep the open-binary and Pro-child guards aligned so only scan workflows cross the Pro boundary and setup or taste reporting cannot recurse.
  • Keep the health, critique, and setup contracts that optional service work must not change local output, exit codes, or hook latency.
  • Preserve the health report contract: repository identity, ruleset identity, full-scan eligibility, and shared service labels must stay stable across relative and absolute targets.
  • Keep foundation item IDs and their evidence states aligned with the account health schema; unknown IDs can invalidate a whole upload.
  • Keep foundation “checked” states conservative when scans are incomplete, advisory findings are hidden, or ignores can conceal evidence.
  • Keep first-viewport thresholds, selector meaning, default viewports, action response rules, and capture names aligned with the build and review contracts.
  • Keep the agent switch catalog, settings JSON, marker format, old taste migration, and supported agent file paths aligned.
  • Keep agent-block writes limited to owned markers and preserve the local-versus-tracked boundary for Cursor rules.
  • Keep walkthrough output metadata aligned with the Needs you attachment contract, including the film hash, poster pair, chapter order, and ship label.
  • Keep walkthrough replacement and locking behavior paired so a rerun cannot publish a film path with the wrong poster or leave partial output.
  • Keep embedded Loop checksum entries aligned with released engine versions; an omitted pin must fail closed rather than download an unverified app.
  • Keep Loop connection journals and helper records aligned with the exact agent account and files changed, including rollback and manual MCP removal guidance.
  • Keep command exit codes and output independent of optional account, setup, health, critique, or Loop service failures.

Important failure modes

TriggerConsequenceGuard
A named router verb is missing from KNOWN_VERBSA same-named path can be treated as a scanRouter coverage test checks named verbs against scan handling
A Pro child starts the open binary without its child guardScan dispatch can recurse or bypass the intended build boundaryis_scan and child environment guards keep Pro dispatch one-way
A partial or opted-out scan reaches health uploadLocal or sensitive scan data is sent when it should not beHealth upload requires a full repository scan and an enabled account choice
A foundation pass is inferred from an incomplete or hidden scanAccount health can show a false project strengthFoundation evidence requires judged files, enabled rules, and no unresolved advisory state
A detached setup probe inherits a caller pipe or runs without a deadlineA normal command can remain open or a hung agent can block setup reportingDetached null streams, bounded inventory, and descendant cleanup
A critique upload or service failure is treated as local report failureA saved report can be lost or a normal review command can fail for a remote reasonLocal-first storage and bounded, optional upload
A first-viewport selector matches nothing or the browser cannot load the pageThe build receives no trustworthy viewport resultRequired selectors, browser launch checks, load timeouts, and failing exit status
A first-viewport action has no response or a dead linkA visually placed primary action does not work for a visitorThe command reloads the page, exercises the action, and checks navigation or page change
A switch block has duplicated, unbalanced, or inline markersThe agent rule file is left unchanged rather than edited unsafelyMarker validation rejects the update before writing
A switch write targets a tracked or shared Cursor rulePersonal guidance can enter source control or change team behaviorGit ownership and local exclusion checks protect the file boundary
ffmpeg is missing or a recording exceeds the walkthrough contractNo usable walkthrough package is returnedTool discovery, duration checks, size limits, and machine-readable failure output
Walkthrough output is replaced during a failed concurrent runThe film and poster can refer to different recordingsPer-output locking, temporary files, and paired placement
A Loop asset has no matching pinned checksumThe app may be replaced with unverified codeEmbedded manifest lookup and SHA-256 verification fail closed
Loop update runs while the app is open or the swap failsThe installed app can be unusable or the update can be unsafeRunning-app refusal and staged swap recovery preserve the old app
Loop disconnect uses today's account instead of the recorded targetHooks or MCP settings can be removed from the wrong agent accountRecorded targets and agent journals drive disconnect
A Loop connect fails after changing hooks or meets a changed filePersonal hooks can be lost or Loop can keep waking an agent unexpectedlyJournal recovery, ownership checks, and rollback of only new changes

Key files

FileWhy to read it
crates/…/main.rsShows the process boundary, Pro scan handoff, setup scheduling, stream flush, and final exit behavior.
crates/…/lib.rsShows the embeddable router surface, native capture adapters, agent-block module, and setup-report entry point.
crates/…/router.rsDefines command dispatch, scan detection, capability wiring, health follow-up, browser-host registration, and native service boundaries.
crates/…/first_viewport.rsShows the browser-based first-screen gate and optional review capture flow.
crates/…/agent_block.rsDefines the shared agent switch catalog, rule-file ownership, migration, and safe write boundary.
crates/…/lib.rsDefines the shared command I/O contract.
crates/…/lib.rsDefines the rule-core boundary used by native and other hosts.
crates/…/rules.rsIllustrates pure visual and contrast decisions shared by scan engines.
crates/…/foundations.rsShows how the project roadmap combines local evidence with detector results and optional health reporting.
crates/…/walkthrough.rsShows the recording-to-attachment workflow and its output contract.
crates/…/setup_report.rsShows how optional setup reporting runs outside the user-facing command.
crates/…/loop_install.rsShows the Loop installation and update boundary.
crates/…/loop_connect.rsShows agent MCP and hook connection ownership, rollback, and disconnect behavior.
crates/…/loop-checksums.txtDefines the release pins trusted by the Loop installer.
crates/…/pro_dispatch.rsShows which commands cross into Pro and how child recursion is blocked.
crates/…/health.rsShows the conditions and invariants for optional design-health sync.
crates/…/critiques.rsShows local-first critique reporting and service-boundary guarantees.
crates/…/setup.rsShows detached setup reporting and hook exclusions.
crates/…/loop_connect.rsShows exact agent connection, rollback, account targeting, and disconnect guarantees.
crates/…/loop_install.rsShows the safety guarantees for Loop download, staging, update, and recovery.