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 group | Purpose | Owning workflow |
|---|---|---|
detect, ignores | Find design issues in local targets or URLs and manage detector exclusions | impeccable-detect |
foundations | Check the project roadmap items that local files and scans can prove | Native foundation workflow |
login, logout, whoami, health, setup, critiques | Manage account access, design-health state, setup reporting, and critique reporting | impeccable-account |
status, switches, switches-refresh | Inspect and synchronize design instructions used by installed agents | Account setup and native agent-block workflows |
skills, help, install, link, update, check | Manage the installed skill and its launcher integration | impeccable-skills |
loop | Install, update, connect, or disconnect the optional macOS Loop app | Native CLI adapter |
walkthrough | Turn a recording into a walkthrough film, poster, and post data | Native media adapter |
agents, mcp | Run agent-facing services and presence or protocol workflows | impeccable-agents and impeccable-mcp |
| Context verbs | Build and inspect project context used by design workflows | impeccable-context |
comp-spec, comp-diff, font-match, build-phase, first-viewport, shot | Specify, compare, inspect, and gate visual fidelity work | impeccable-comp-verbs and native visual adapters |
hook, hook-before-edit, hooks | Run edit checks, pre-edit gates, and hook administration | impeccable-hook |
live* | Start and control the live design workflow | impeccable-live |
component-review, capture-server, motion-capture | Produce review previews and connect native capture to host workflows | CLI 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 concern | Contract |
|---|---|
| Film | Up to two minutes and 50 MB |
| Chapters | Up to 12 ordered moments with short one-line labels |
| Poster | A still taken from the finished film |
| Output | One 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, andKNOWN_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
| Trigger | Consequence | Guard |
|---|---|---|
A named router verb is missing from KNOWN_VERBS | A same-named path can be treated as a scan | Router coverage test checks named verbs against scan handling |
| A Pro child starts the open binary without its child guard | Scan dispatch can recurse or bypass the intended build boundary | is_scan and child environment guards keep Pro dispatch one-way |
| A partial or opted-out scan reaches health upload | Local or sensitive scan data is sent when it should not be | Health upload requires a full repository scan and an enabled account choice |
| A foundation pass is inferred from an incomplete or hidden scan | Account health can show a false project strength | Foundation evidence requires judged files, enabled rules, and no unresolved advisory state |
| A detached setup probe inherits a caller pipe or runs without a deadline | A normal command can remain open or a hung agent can block setup reporting | Detached null streams, bounded inventory, and descendant cleanup |
| A critique upload or service failure is treated as local report failure | A saved report can be lost or a normal review command can fail for a remote reason | Local-first storage and bounded, optional upload |
| A first-viewport selector matches nothing or the browser cannot load the page | The build receives no trustworthy viewport result | Required selectors, browser launch checks, load timeouts, and failing exit status |
| A first-viewport action has no response or a dead link | A visually placed primary action does not work for a visitor | The command reloads the page, exercises the action, and checks navigation or page change |
| A switch block has duplicated, unbalanced, or inline markers | The agent rule file is left unchanged rather than edited unsafely | Marker validation rejects the update before writing |
| A switch write targets a tracked or shared Cursor rule | Personal guidance can enter source control or change team behavior | Git ownership and local exclusion checks protect the file boundary |
ffmpeg is missing or a recording exceeds the walkthrough contract | No usable walkthrough package is returned | Tool discovery, duration checks, size limits, and machine-readable failure output |
| Walkthrough output is replaced during a failed concurrent run | The film and poster can refer to different recordings | Per-output locking, temporary files, and paired placement |
| A Loop asset has no matching pinned checksum | The app may be replaced with unverified code | Embedded manifest lookup and SHA-256 verification fail closed |
| Loop update runs while the app is open or the swap fails | The installed app can be unusable or the update can be unsafe | Running-app refusal and staged swap recovery preserve the old app |
| Loop disconnect uses today's account instead of the recorded target | Hooks or MCP settings can be removed from the wrong agent account | Recorded targets and agent journals drive disconnect |
| A Loop connect fails after changing hooks or meets a changed file | Personal hooks can be lost or Loop can keep waking an agent unexpectedly | Journal recovery, ownership checks, and rollback of only new changes |
Key files
| File | Why to read it |
|---|---|
| crates/…/main.rs | Shows the process boundary, Pro scan handoff, setup scheduling, stream flush, and final exit behavior. |
| crates/…/lib.rs | Shows the embeddable router surface, native capture adapters, agent-block module, and setup-report entry point. |
| crates/…/router.rs | Defines command dispatch, scan detection, capability wiring, health follow-up, browser-host registration, and native service boundaries. |
| crates/…/first_viewport.rs | Shows the browser-based first-screen gate and optional review capture flow. |
| crates/…/agent_block.rs | Defines the shared agent switch catalog, rule-file ownership, migration, and safe write boundary. |
| crates/…/lib.rs | Defines the shared command I/O contract. |
| crates/…/lib.rs | Defines the rule-core boundary used by native and other hosts. |
| crates/…/rules.rs | Illustrates pure visual and contrast decisions shared by scan engines. |
| crates/…/foundations.rs | Shows how the project roadmap combines local evidence with detector results and optional health reporting. |
| crates/…/walkthrough.rs | Shows the recording-to-attachment workflow and its output contract. |
| crates/…/setup_report.rs | Shows how optional setup reporting runs outside the user-facing command. |
| crates/…/loop_install.rs | Shows the Loop installation and update boundary. |
| crates/…/loop_connect.rs | Shows agent MCP and hook connection ownership, rollback, and disconnect behavior. |
| crates/…/loop-checksums.txt | Defines the release pins trusted by the Loop installer. |
| crates/…/pro_dispatch.rs | Shows which commands cross into Pro and how child recursion is blocked. |
| crates/…/health.rs | Shows the conditions and invariants for optional design-health sync. |
| crates/…/critiques.rs | Shows local-first critique reporting and service-boundary guarantees. |
| crates/…/setup.rs | Shows detached setup reporting and hook exclusions. |
| crates/…/loop_connect.rs | Shows exact agent connection, rollback, account targeting, and disconnect guarantees. |
| crates/…/loop_install.rs | Shows the safety guarantees for Loop download, staging, update, and recovery. |