// Blog / inspector
Visual inspector for AI coding agent trust and freshness
A trust layer is only useful if humans can see what is trusted, stale, suspect, and waiting for repair.
// direct answer
Short answer
A visual inspector turns .knowledge artifacts into an operating surface: health, trust buckets, freshness, repair queue, graph relationships, and critical paths. It does not replace the files; it makes the files reviewable by humans before agents act.
Understand what a visual inspector adds on top of repo-local knowledge files.
// real failure mode
The failure mode
A repository can contain trust reports and stale markers, but the team may never inspect them because they are buried in JSON.
The agent might know a module is suspect while the human reviewer sees only a clean-looking PR.
Without a visual surface, trust debt stays invisible until a wrong-file edit or stale-summary failure reaches review.
// visual workflow
The inspector fix
The Inspector renders the trust layer as a dashboard: health score, trust graph, module status, repair queue, and policy warnings.
It lets a reviewer see what the agent should recheck before code changes, especially around stale modules and critical paths.
The static local Inspector ships with the open core. Inspector Pro is the paid workflow layer for interactive team review.
// concrete example
When a module looks safe but is not
A PR modifies runtime execution. The code diff is small, but the module summary is stale and linked evidence is incomplete.
The Inspector surfaces the stale module, the missing evidence, and the repair item before review handoff.
The reviewer can ask the agent to re-read source and tests instead of approving a change against stale context.
// repo proof
Repo proof to inspect
.knowledge/inspector/index.html
The local dashboard is generated from repo-local artifacts and can be opened without a cloud service.
- Visual trust review
- Checking repair queue state
- Editing source files
- Replacing code review
.knowledge/maintenance/trust_report.json
The Inspector view should reflect the current trusted, suspect, stale, and low-confidence buckets.
- Trust bucket display
- Review readiness checks
- Claiming product behavior without source
.knowledge/freshness.json
Freshness shows which knowledge artifacts may need recheck after source changes.
- Stale module warnings
- Post-commit maintenance
- Ignoring current git changes
.knowledge/maintenance/repair_queue.json
Repair items convert uncertainty into visible work the team can assign.
- Prioritizing rechecks
- Team review conversations
- Blocking every small edit
// command transcript
Commands and expected checks
node .knowledge/tools/build-visual-inspector.js - expected
- The static Inspector is regenerated from current .knowledge artifacts.
- inspect next
- .knowledge/inspector/index.html
node .knowledge/tools/serve-inspector.js - expected
- The generated Inspector can be served locally for review.
- inspect next
- Browser preview of the local Inspector
node .knowledge/tools/doctor.js - expected
- The health status feeding the visual layer is checked.
- inspect next
- .knowledge/maintenance/quality_report.json
What the human should see
// field guide
Inspector signals
| Signal | Question it answers | Reviewer action |
|---|---|---|
| Health | Is the knowledge layer usable today? | Run doctor or refresh before handoff. |
| Trust | Can the agent use this summary for planning? | Re-read source when trust is weak. |
| Freshness | Did code move after the summary? | Rebuild or repair stale artifacts. |
| Repair queue | What should not stay implicit? | Assign or close the repair item. |
// guardrails
What the agent should not trust blindly
- The Inspector is a view over files, not a new source of truth.
- A green visual state should still not override current code and tests.
- Use the visual layer to catch stale context before it becomes a PR review problem.
// common mistakes
Common mistakes
- Treating the dashboard as magic instead of generated state.
- Showing graph visuals without source-of-truth rules.
- Hiding repair items because they make the dashboard less pretty.
// quick FAQ
FAQ
Does the Inspector require cloud sync?
The static local Inspector can be generated from repository files. Inspector Pro is the paid workflow layer for team operations.
What is the most important Inspector signal?
Trust state. If a module is stale, suspect, or low-confidence, the agent should re-read current source and tests before behavior claims.
// page-specific next step
Use this page when trust needs to become visible
Generate the static Inspector from the repo-local artifacts, then use it to decide what an agent must re-read before acting.