Repository technologies, skill catalog and doctor
The controller keeps versioned technology, catalog and diagnostic artifacts in the existing SQLite database. These records are separate from session cleanup. Reading them does not install dependencies, activate skills or repair configuration.
Run diagnostics
devctl doctor
devctl doctor --no-ai
devctl doctor project PROJECT_ID --json
devctl doctor repository PROJECT_ID --no-ai --json
devctl doctor host HOST_ID --no-ai
devctl diagnostics current --project PROJECT_ID
devctl diagnostics repair REPORT_ID FINDING_ID --revision FINDING_REVISION_SHA256
devctl diagnostics repair-status REPAIR_ID
Plain devctl doctor defaults to deterministic current findings. Optional
account-backed analysis is requested explicitly with --ai; --no-ai remains
supported. The plain output names the affected target, observed/expected state,
impact and next action, including an exact revision-bound repair command when
a safe fix is available. The repair CLI builds {expectedRevision} itself;
no JSON input file is required.
The existing service and bundle diagnostic commands remain compatible.
The new report has schemaVersion: "1.0". Its exit codes are:
| Code | Meaning |
|---|---|
| 0 | Selected diagnostics completed without a diagnosed failure |
| 1 | Completed checks found a diagnostic failure |
| 2 | Diagnosis is incomplete, including disabled/blocked/unknown checks |
| 3 | A check or the controller/source path could not execute reliably |
A diagnosed failure takes precedence over incomplete checks. A partial report
can contain successful completed checks; that does not mean every check passed.
When the controller or sign-in credential is unavailable, the CLI reports local
Node and credential-presence checks, marks remote sources unavailable and uses
exit 3. It does not guess the server's account assignment or persist the fallback
on an unavailable server. --json produces JSON without terminal decoration.
POST /v1/doctor/runs accepts {scope, projectId?, hostId?, ai, checks?}.
Scopes are installation, host, project and repository. checks selects registered
AI check IDs; deterministic snapshot probes always run. GET /v1/doctor/runs
supports projectId, time bounds, a maximum 100 items and cursor pagination.
GET /v1/doctor/runs/:id reads a report; GET /v1/doctor/export exports the same
authorized page as JSONL, with X-Next-Cursor when another page is available.
GET /v1/doctor/current accepts scope, projectId and hostId for the same
authorized scopes. It observes current deterministic state without launching a
model or host job. Current snapshots remain bounded per owner and scope; explicit
runs and repair verification retain immutable History. Reports add typed
findings, observationRevision and currentStatus while preserving older
saved check records.
The shared diagnostics panel exposes reports, check blockers, repository technology evidence, recommendations, catalog freshness and report history. Open Projects or Sessions → Workflows (Shift+W) → Diagnostics and skills, or Settings → Diagnostics for installation scope. The same panel is mounted in the terminal, browser and desktop shell. Finding labels are translated; observed evidence and resource names remain literal. Its initial current-state read does not launch an AI check. The AI action uses the assigned Control Room account and shared execution admission.
Read a finding and act on it
Dashboard shows the current problem count and Open Doctor (Shift+D). Doctor's main view contains current problems grouped by affected target, with plain-language Impact, Observed, Expected and next-step fields. Browser cards and the native target/problem tree share the same typed findings. Disabled optional features are excluded from current problems. An empty view reports No current problems for the displayed check time.
Choose Fix (f) only when the finding exposes a safe operation. Choose the
relevant settings action (o) for manual work, or Recheck configuration (v)
for a fresh deterministic report without paid AI analysis. Raw check IDs,
evidence and earlier execution records stay in Details and History. Opening a
setting is not a completed repair, and recommendation text is never executed.
History reports are clearly labeled as saved observations; an older report is
not projected into current problems without a fresh check.
POST /v1/doctor/runs/:reportId/findings/:findingId/repair accepts only
{expectedRevision} from the selected finding. The controller rechecks owner,
current state and revision, then admits the stored safe action. Supported fixes
are bounded repository metadata scans and retries of already-approved native
permission delivery. There is no provider restart or destructive cleanup action.
The request is idempotent for the exact admitted repair.
Both that response and GET /v1/doctor/repairs/:id return a separate repair
receipt plus a fresh report when verification is available. UI progress follows
the actual queued/running/verified/failed/unverified/obsolete state. Verified
requires a matching trusted host result and a new check in which the finding is
absent. A queued command, successful request or settings link cannot establish
that result. A failed status read retains the last confirmed state. Repairs do
not depend on the console staying open.
Checks and the missing-account count
Deterministic checks extend the existing diagnoseState implementation:
controller readability, client/host connectivity, stale host inventory,
disk/GPU observations, project checkout/container/session information, resource
routes, forwards, service health, provider sign-in and permission delivery.
Additional checks report missing/partial/stale technology snapshots, declared
versus resolved version disagreements, catalog freshness and supplied review
coverage. Fresh single-observation CPU/memory pressure warns at 90%; stale or
missing observations remain unknown and are not sustained-capacity evidence.
Missing telemetry is unknown; this does not actively scan new hosts or
probe arbitrary services. Host capacity and actual service behavior remain
limited by the inventory/probe sources already implemented by devctrl.
Two registered AI-assisted checks perform additional analysis:
ai.stack-consistency: compare component technology evidence with configured environment/runtime requirements and effective review coverage.ai.operational-evidence: analyze permitted resource/state evidence and propose concrete configuration, capacity and skill improvements.
Each applicable check and target has one result. missingAccountChecks is the
number of distinct checkId + targetId pairs with applicable status, blocked
execution and account_not_assigned among their blockers. Source problems can
coexist with that blocker. Attempts, skill counts, not-applicable targets,
explicitly disabled checks and unknown applicability do not inflate this count.
An assigned but unavailable, forbidden, unsupported or quota-exhausted account
is not counted as an unassigned account and never counts as available.
For a project target, both checks are applicable. Repository scope selects stack consistency; installation also includes an operational target and bounded project targets. Without an account, a one-project report therefore normally lists two additional checks. Assigning the account does not remove source, model, permission, quota or budget blockers automatically.
AI execution uses the exact Control Room account, project data permissions,
runtime capabilities and the shared durable reservation ledger. It never picks
an arbitrary substitute account. Evidence-only Claude diagnostics require the
adapter's conservative Claude Code 2.1.292-or-newer compatibility baseline.
Native restricted mode disables built-in tools, slash commands and settings
sources; a backend allowlist permits only task/evidence retrieval and result
delivery. The diagnostic process disables CLAUDE.md instruction memory,
auto-memory, policy skills, attachments, Git context and IDE auto-connect. It
skips the runtime-guide/project-context attachment and interchange add-directory
access, and does not inherit project environment or configuration synchronization.
The existing account OAuth mode is preserved; --bare is unsuitable because it
disables subscription authentication.
A local read-only CLI version/flag and executable-marker probe established this adapter baseline. It did not make a model call or verify versions or behavior on enrolled hosts. Authenticated diagnostic execution still needs separate live verification. Codex diagnostic execution remains unsupported until an equivalent verified evidence-only capability exists. Skills may be delivered to Codex for other authorized workflows; that does not imply doctor tool restrictions exist there.
Installation/host analysis needs an explicitly selected owned Git execution
project. Read or update it with GET/PUT /v1/doctor/execution-source, body
{projectId: "OWNED_PROJECT_ID"}. Project diagnostics use their own project.
The chosen account/host/runtime must also be admitted by that project's
execution policy. Unknown quota/cost requires the bounded explicit policy
supported by admission. Accounts, reservations, terminal task states and
timeouts are retained in normal coordination history.
AI authentication is host-local: the exact assigned account must already be
ready and logged in on the selected execution host. An explicitly selected model
also needs current installed model-catalog evidence there. Creating a VM does not
transfer that account's authorization. Managed provisioning requires
accountPreparation: "existing-accounts-flow"; the task visibly waits for the
existing account import/login flow before native launch. Fully unattended native
credential transport onto a fresh VM is incomplete P1 implementation, rather
than merely an unverified live path.
Reports keep requested identity separate from observed identity. Actual model metadata and usage remain unknown when the native adapter cannot attest them. AI output is schema validated; malformed output or execution failure preserves the deterministic report and cannot turn its failures into a pass. Findings are facts or hypotheses with evidence references, action, priority and expected effect. No recommendation grants permission to apply it.
Technology snapshots
POST /v1/projects/:id/technologies/refresh queues a bounded host scan of a
trusted managed workspace; optional workspaceId must belong to the project
and caller. GET /v1/projects/:id/technologies collects its result or returns
the retained profile and pending/unknown reason. The history endpoint adds
/history with bounded cursor pagination. A normal agent cannot supply arbitrary
filesystem paths or forged inventory through this API.
The technology endpoint and /export accept technology, component (ID or
path), and coverage=assigned|observed|unassigned|unknown. They return a derived
selection alongside the full immutable profile. Coverage lists explicit required
check IDs and exact-subject observations; an empty assignment list has no implied
execution percentage. /snapshots/:snapshotId retrieves an older authorized
profile referenced by a report. Catalog /history and /snapshots/:snapshotId
provide the corresponding immutable catalog records.
An administrator may POST /technologies/annotations with
{kind: "clarification" | "exclude", technologyId, componentId?, reason}.
The controller records the authenticated actor and UTC time in a new snapshot;
original detected facts remain present. Exclusions are visible user annotations,
not permission to suppress required review checks. They do not change the
detection/matching digest or silently turn declared evidence into non-applicable.
The host collector reads explicitly recognized inputs, with no package manager, configuration evaluation or repository script execution. It rejects symlinks, validates scope, checks the opened Linux inode path and enforces file, byte, depth and time bounds. Host-result transport imposes a smaller aggregate read budget than the collector's absolute maximum. Vendor/generated/build directories and secret/configuration files outside the explicit input names are excluded.
For Git-backed scans, the host captures the full trusted head/base/dirty/untracked subject before and after scanning, and restricts inputs to tracked and admitted untracked Git paths. A stable comparison binds the profile to that subject. Unavailable base/remote metadata or a moving checkout leaves an explicitly bounded inventory fingerprint; it is never relabeled an exact commit/tree hash. Subject completeness and parser completeness are separate: even an exactly bound subject can have partial parser coverage.
Component roots come from package/module manifests. Facts retain category, component path, direct/transitive/unknown relation, dependency kind, source kind, declared constraint and separately resolved version. Each fact cites its input hash, field/rule and parser version. Multiple versions in separate components remain separate. Root tooling is not automatically declared active in every component. Dependency presence does not establish actual runtime use.
| Family | Supported bounded data extraction | Explicit limitations |
|---|---|---|
| JS/TS/Node | package.json dependencies/engines/workspaces/packageManager; npm locks v2/v3 packages; pnpm v9 package keys; Yarn classic/Berry literal version records | pnpm importer/peer graph and Yarn selectors are not resolved; workspace globs are not executed |
| Python | Literal PEP 621 arrays, Poetry declarations, requirements lines, setup.cfg install_requires, Poetry/uv package name/version pairs, Pipfile.lock records | Not a full TOML/INI parser; markers, dynamic metadata, editable/includes and setup.py remain unsupported/partial |
| Go/Rust | go.mod literal requirements/go version; go.work presence; Cargo manifest dependencies and lock package pairs | No module graph; replace/use/inheritance/conditional targets are not evaluated; go.sum alone does not establish resolved use |
| JVM/Android | Literal Maven dependency elements; Gradle implementation/api/test literals; version catalog literal modules/versions | No parent/property/profile resolution, Gradle execution, alias-use graph or Android build evaluation |
| Swift/iOS | Package.resolved v1/v2/v3 pins; Package.swift URL/version literals; Podfile.lock versions; literal Xcode Swift settings | No Swift/Ruby execution, target conditions, pod graph or inferred full Xcode model |
| .NET | Literal project/central package XML references; NuGet lock v1 direct/transitive/resolved records | XML entities rejected; imports, MSBuild conditions and central inheritance are not evaluated |
| PHP/Ruby/Dart | Composer manifests/locks, Gemfile literals/Bundler spec versions, pubspec declarations/version records | Conditional Ruby/YAML expressions, overrides and complete transitive/source graphs are not resolved |
| Infrastructure | Docker/devcontainer/Compose/Wrangler/Terraform configuration presence | Presence is configuration evidence, not proof of a running platform |
Malformed, dynamic or unfamiliar inputs add partial/unsupported evidence. The bounded parser cache keys content hashes, path/component and parser version. Manual refresh, newly observed repository contexts and captured review subject changes use the same snapshot path. No universal dependency-analysis engine is implied.
Local language statistics use documented extensions and file sizes, exclude
generated/vendor paths, and report byte denominators. Optional
POST /v1/projects/:id/technologies/github-languages/refresh reads GitHub's
Languages API through the owned Git connection when configured. Its separate
informational artifact has subjectBound: false: asynchronous default-branch
Linguist bytes do not attest a PR SHA and do not replace the review snapshot.
API failures preserve previous statistics; connector access and AI account
assignment are distinct. Language bytes are not LOC, importance or review quality.
Matching, catalog and activation
Matching version technology-match-1 returns match, non-match or unknown with
component/evidence/profile digests. Supported version comparisons are deliberately
bounded numeric exact, caret, tilde and inequality conjunctions. Ambiguous ranges
remain unknown. Required review applicability retains base/head evidence, so
deleting a manifest cannot silently remove its required checks. An incomplete
scan cannot prove a negative technology match.
The initial catalog contains actual maintained bundles:
devctl-review-node, devctl-review-python, devctl-doctor-evidence. Each has
complete file hashes, an immutable content revision, declared MIT-0 license,
purpose tags and runtime delivery evidence. Content is reviewed; runtime
execution is explicitly unverified. These small bundles do not embed scripts,
remote dependencies or organization-specific Sentry/Trail of Bits policies.
GET /v1/skill-catalog supports technology filtering, name/repository-stars
sorting and bounded offset pages. GET /v1/projects/:id/skill-recommendations
adds purpose/runtime/relevance filters and preserves the technology/catalog/rule
versions and proposed repository assignment scope. Fit, purpose, runtime
compatibility and content verification precede popularity in relevance order.
Stars belong to a repository, not an individual bundle, and do not measure
safety or review quality. Unknown tags/license/tool requirements remain unknown.
The controller checks the fixed public source `https://data.devctrl.dev/skills/v1/catalog.json` every 24 hours, independently of GitHub discovery. One server download feeds separate owner catalogs; no owner, repository, credential or private search term is sent to that URL. It runs without an open console. The Catalog tab shows its last successful check, next attempt, cached entry count and source failure.
The importer accepts the observed publisher's numeric-v1 category format and
the existing strict SkillCatalogSnapshot v1 contract, with at most 2,000 rows
and an 8 MiB response. The public source was read on 2026-10-24: its 23 categories
contained 230 rows and 190 unique skills. Duplicate category appearances merge
only when their pinned source metadata agrees. The source's bounded-discovery
warnings remain partial coverage rather than a complete Internet inventory.
Published entries have digestKind:"metadata", an empty file inventory and
explicit source/category/version/static-token-estimate metadata. Their digest
identifies that metadata; it is not a bundle content pin. Format, completeness,
content review, license verification and runtime compatibility remain unknown;
execution is unverified. The feed supplies neither file-content hashes nor a
detached signature. Unknown formats/signature envelopes are rejected. Installation,
binding and review pinning require fetching and verifying the actual complete
bundle first; metadata cannot be installed or pinned through the existing APIs.
The native/browser Catalog view pages entries and marks this boundary visibly.
Reading the live source does not establish a deployed controller refresh or
successful third-party skill execution.
Conditional ETags avoid repeated payload downloads. A successful check schedules
the next one after 24 hours; failures use bounded retry backoff and Retry-After.
Fetch, format and integrity errors keep the last valid cache and owner catalogs.
Publication preserves private discoveries and locally maintained bundles; a
combined catalog exceeding the bound is rejected without dropping those records.
Neither refresh changes active assignments, bindings or pinned versions.
GET/PUT /v1/skill-catalog/refresh inspects/configures the independent GitHub
discovery job. Its default interval remains 168 hours; it can be disabled or
changed within bounded limits without disabling the daily source. POST checks
the daily source immediately and requests an owned GitHub refresh. Settings
include request/repository/
bundle bounds, enumerated public technology terms, an owned GitHub connector
and explicitly configured source repositories. Public search never includes
private project names, manifests, snippets or secrets. Private source metadata
stays within its owner scope.
Refresh uses repository search and bounded immutable trees/blobs, not anonymous code search. It validates real SKILL.md frontmatter, full bounded bundle inventory and supporting references without executing scripts. Conditional requests/ETags, rate-limit backoff, Retry-After, checkpoints, durable duplicate leases and versioned refresh history preserve usable previous entries on partial failure. Missing search results never prove deletion. Repository metadata is shared by its bundles; stable repository IDs preserve renamed-source identity. Binary or oversized bundles and unsupported frontmatter remain unverified.
Catalog refresh changes recommendations, never active assignments, pinned versions or review contracts. Installation and activation use the existing authorized skill/profile flow with the complete pinned bundle. Assignment coverage and trusted observed execution are separate records for the exact review subject; LLM-only claims do not become trusted-tool completion.
Verification and current limits
Static parser fixtures, path/symlink/size boundaries, subject matching, manifest deletion, exact missing-account counts, disabled/additional blockers, AI-output validation/redaction, history/API ownership, ETag/rate-limit/concurrent refresh and partial-snapshot preservation have automated tests. AI-check unit tests use injected executors and are not live provider tests. GitHub refresh tests use a deterministic HTTP adapter; they do not establish live GitHub coverage or private-token permissions. No paid diagnostic session or third-party bundle code was executed as part of these tests.
Primary format and source references checked 2026-10-21: Agent Skills, npm locks, PyPA pyproject, Cargo manifests, Gradle catalogs, NuGet references, GitHub Languages, GitHub search, GitHub API practices.