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:

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.