@stsepelin/checktrail 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -4,18 +4,22 @@ Local code validation with a CLI, MCP tools, and evidence of what actually ran.
 
 Formerly Repo Verifier. See the [rename guide](docs/RENAMING.md) for existing source checkouts.
 
-**Experimental preview: 0.1.0-alpha.1.** Public source is available at
+**Published preview: 0.1.0-alpha.1; alpha.2 is in preparation.** Public source is available at
 [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
 See [implementation status](docs/STATUS.md), the [plan](docs/PLAN.md) and the
 [language matrix](docs/LANGUAGES.md) before relying on an adapter.
 [Installation](docs/INSTALLATION.md) covers the CLI, Claude Code and Codex.
+[Agent skills](docs/SKILLS.md) provides setup, validation and review workflows
+installable with `npx skills add stsepelin/checktrail`.
+[Project setup](docs/ONBOARDING.md) covers the alpha.2 candidate's `init`, `doctor`
+and MCP configuration generator.
 [Release preparation](docs/RELEASE.md) records publication and verification gates. The
 [milestone audit](docs/ACCEPTANCE.md) separates implemented profiles from open
 acceptance work; [client checks](docs/CLIENTS.md) record actual application coverage.
 
-The [13-job hosted matrix](https://github.com/stsepelin/checktrail/actions/runs/35573066804)
-passed at `52ba415` on Linux and macOS. This identifies a verified source revision;
-it does not imply that a later package version has been published.
+The [hosted matrix](https://github.com/stsepelin/checktrail/actions/runs/35585998184)
+passed at `bfc8cc4` on Linux and macOS. That result predates the alpha.2 candidate;
+new release changes require their own CI run and package verification.
 
 Checktrail discovers projects, plans registered checks, invokes native tools
 when explicitly trusted, and reports results without turning skipped or empty
@@ -41,7 +45,7 @@ node dist/src/cli.js run --root examples/javascript --trust-project --detailed
 `--trust-project`: tests, compiler plugins and project configuration can execute
 code with your user privileges. This is not a sandbox.
 
-Commands always return JSON except help/version. Exit codes:
+Successful commands return JSON except help/version; input errors use stderr. Exit codes:
 
 | Code | Meaning                                                                                 |
 | ---- | --------------------------------------------------------------------------------------- |

package/dist/src/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import path from "node:path";
+import { initialize, diagnose, mcpConfiguration, mcpClients, } from "./onboarding.js";
 import { createReviewContext, projectReviewContext, receiveReview, projectReviewReceipt, } from "./review.js";
 import { fetchPolicyPack } from "./fetch-pack.js";
 import { externalReferencesSchema, loadExternalAdapters, } from "./external-adapter.js";
@@ -22,11 +23,15 @@ import { VERSION } from "./types.js";
 import { validateContracts, projectContractReport } from "./contracts.js";
 import { compareRuntimeInventories, projectRuntimeComparison, } from "./runtime-inventory.js";
 async function main() {
-    const { values, positionals } = parseArgs({
+    const { values, positionals, tokens } = parseArgs({
+        tokens: true,
         allowPositionals: true,
         strict: true,
         options: {
             root: { type: "string", default: "." },
+            write: { type: "boolean", default: false },
+            check: { type: "string", multiple: true },
+            client: { type: "string" },
             "trust-project": { type: "boolean", default: false },
             "allow-execution": { type: "boolean", default: false },
             detailed: { type: "boolean", default: false },
@@ -58,12 +63,29 @@ async function main() {
         return;
     }
     if (values.help || positionals.length === 0) {
-        process.stdout.write("checktrail <inspect|plan|run|serve|adapters|import-junit|export-sarif|create-baseline|compare-findings|compare-runtime|check-contracts|check-architecture|guidance|review-context|review-receipt|mutate|fetch-pack> [--root PATH] [--detailed] [--base REVISION] [--policy-overlay PATH] [--adapter PATH#sha256=DIGEST ...]\nRun: --trust-project [--timeout-ms 30000] [--allow-env NAME ...]\nServe: --allow-execution (optional; disabled by default) [--allow-env NAME ...]\nFetch-pack: --url HTTPS_URL --sha256 DIGEST --output RELATIVE_JSON_PATH\nExit: 0 passed/read-only success/completed advisory experiment, 1 failed checks, 2 incomplete/error\n");
+        process.stdout.write("checktrail <init|doctor|mcp-config|inspect|plan|run|serve|adapters|import-junit|export-sarif|create-baseline|compare-findings|compare-runtime|check-contracts|check-architecture|guidance|review-context|review-receipt|mutate|fetch-pack> [--root PATH] [--detailed] [--base REVISION] [--policy-overlay PATH] [--adapter PATH#sha256=DIGEST ...]\nInit: [--write] [--check PATH#CHECK_ID ...] (preview by default; preserves existing config)\nDoctor: [--detailed] [--policy-overlay PATH] [--allow-env NAME ...] [--adapter PATH#sha256=DIGEST ...] (no execution)\nMcp-config: --client codex|claude-code|claude-desktop|cursor|vscode (prints configuration only)\nRun: --trust-project [--timeout-ms 30000] [--allow-env NAME ...]\nServe: --allow-execution (optional; disabled by default) [--allow-env NAME ...]\nFetch-pack: --url HTTPS_URL --sha256 DIGEST --output RELATIVE_JSON_PATH\nExit: 0 passed/read-only success/completed advisory experiment, 1 failed checks, 2 incomplete/error\n");
         return;
     }
     if (positionals.length !== 1)
         throw new Error("Expected exactly one command");
     const command = positionals[0];
+    for (const token of tokens) {
+        if (token.kind !== "option")
+            continue;
+        if (["write", "check"].includes(token.name) && command !== "init")
+            throw new Error(`--${token.name} applies only to init`);
+        if (token.name === "client" && command !== "mcp-config")
+            throw new Error("--client applies only to mcp-config");
+        const allowed = command === "init"
+            ? ["root", "write", "check"]
+            : command === "doctor"
+                ? ["root", "detailed", "policy-overlay", "allow-env", "adapter"]
+                : command === "mcp-config"
+                    ? ["root", "client"]
+                    : undefined;
+        if (allowed && !allowed.includes(token.name))
+            throw new Error(`--${token.name} does not apply to ${command}`);
+    }
     if (values["allow-review-source"] &&
         (!values.detailed ||
             !["review-context", "review-receipt", "serve"].includes(command)))
@@ -85,7 +107,15 @@ async function main() {
         };
     }));
     if (externalAdapters.length &&
-        !["inspect", "plan", "run", "serve", "adapters", "guidance"].includes(command))
+        ![
+            "inspect",
+            "plan",
+            "run",
+            "serve",
+            "adapters",
+            "guidance",
+            "doctor",
+        ].includes(command))
         throw new Error("External adapters apply only to inspection, planning, validation, serving and derived guidance");
     if (externalAdapters.length && command === "guidance" && values.input)
         throw new Error("External adapters require derived guidance, not an imported context");
@@ -103,7 +133,49 @@ async function main() {
         ]);
         return;
     }
+    if (command === "doctor") {
+        const result = await diagnose(values.root, {
+            detailed: values.detailed,
+            externalAdapters,
+            environment: inheritEnvironment(values["allow-env"] ?? []),
+            ...(values["policy-overlay"]
+                ? { policyOverlay: values["policy-overlay"] }
+                : {}),
+        });
+        print(result);
+        process.exitCode = result.status === "no-static-blockers" ? 0 : 2;
+        return;
+    }
     const root = await realpath(values.root);
+    if (command === "init") {
+        const selections = new Map();
+        for (const value of values.check ?? []) {
+            const split = value.lastIndexOf("#");
+            if (split <= 0 || split === value.length - 1)
+                throw new Error("Check selection requires PATH#CHECK_ID");
+            const selectedPath = value.slice(0, split);
+            selections.set(selectedPath, [
+                ...(selections.get(selectedPath) ?? []),
+                value.slice(split + 1),
+            ]);
+        }
+        const result = await initialize(root, {
+            write: values.write,
+            selections: [...selections].map(([selectedPath, checks]) => ({
+                path: selectedPath,
+                checks,
+            })),
+        });
+        print(result);
+        process.exitCode = result.status === "needs-selection" ? 2 : 0;
+        return;
+    }
+    if (command === "mcp-config") {
+        if (!mcpClients.includes(values.client))
+            throw new Error(`mcp-config requires --client ${mcpClients.join("|")}`);
+        print(await mcpConfiguration(root, values.client));
+        return;
+    }
     if (command === "fetch-pack") {
         if (!values.url || !values.sha256 || !values.output)
             throw new Error("fetch-pack requires --url HTTPS_URL --sha256 DIGEST --output RELATIVE_JSON_PATH");

package/dist/src/index.d.ts

@@ -3,6 +3,8 @@ export { validateContracts } from "./contracts.js";
 export type { ContractBundle, ContractReport } from "./contract-schema.js";
 export type { PlanOptions, ValidationOptions } from "./engine.js";
 export { adapters } from "./adapters.js";
+export { initialize, diagnose, mcpConfiguration, mcpClients, } from "./onboarding.js";
+export type { InitOptions, InitResult, DoctorIssue, DoctorResult, McpClient, } from "./onboarding.js";
 export type { PolicyPack, PackReference } from "./policy-pack.js";
 export { fetchPolicyPack } from "./fetch-pack.js";
 export type { FetchPackOptions, FetchedPack } from "./fetch-pack.js";

package/dist/src/index.js

@@ -1,6 +1,7 @@
 export { createPlan, validate, aggregate } from "./engine.js";
 export { validateContracts } from "./contracts.js";
 export { adapters } from "./adapters.js";
+export { initialize, diagnose, mcpConfiguration, mcpClients, } from "./onboarding.js";
 export { fetchPolicyPack } from "./fetch-pack.js";
 export { projectPlan, projectReport } from "./output.js";
 export { importJUnit } from "./junit.js";

package/dist/src/onboarding.d.ts

@@ -0,0 +1,50 @@
+import { type Config } from "./config.js";
+import { type PlanOptions } from "./engine.js";
+export interface InitOptions {
+    write?: boolean;
+    selections?: {
+        path: string;
+        checks: string[];
+    }[];
+}
+export interface InitResult {
+    schemaVersion: 1;
+    engineVersion: string;
+    status: "preview" | "created" | "preserved" | "needs-selection";
+    configuration: Config | null;
+    unresolved: {
+        path: string;
+        adapter: string;
+        choices: string[];
+    }[];
+    executionEnabled: false;
+}
+export declare function initialize(root: string, options?: InitOptions): Promise<InitResult>;
+export interface DoctorIssue {
+    code: "configuration-error" | "empty-plan" | "unselected-project" | "unavailable-check" | "missing-executable" | "package-metadata" | "unsupported-platform";
+    check?: string;
+    adapter?: string;
+    project?: string;
+    detail?: string;
+}
+export interface DoctorResult {
+    schemaVersion: 1;
+    engineVersion: string;
+    status: "no-static-blockers" | "attention-required";
+    validationPerformed: false;
+    projects: number;
+    checks: number;
+    issues: DoctorIssue[];
+    unverified: string[];
+}
+export declare function diagnose(root: string, options?: Omit<PlanOptions, "base"> & {
+    detailed?: boolean;
+}): Promise<DoctorResult>;
+export declare const mcpClients: readonly ["codex", "claude-code", "claude-desktop", "cursor", "vscode"];
+export type McpClient = (typeof mcpClients)[number];
+export declare function mcpConfiguration(root: string, client: McpClient): Promise<{
+    client: McpClient;
+    format: "json" | "toml";
+    configuration: string;
+    executionEnabled: false;
+}>;

package/dist/src/onboarding.js

@@ -0,0 +1,295 @@
+import { constants } from "node:fs";
+import { access, link, lstat, mkdtemp, realpath, rm, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { adapters, checksFor } from "./adapters.js";
+import { configSchema } from "./config.js";
+import { createPlan } from "./engine.js";
+import { inventory, readProjectFile } from "./inventory.js";
+import { identifyTool } from "./tool-versions.js";
+import { VERSION } from "./types.js";
+async function configurationExists(root) {
+    try {
+        const entry = await lstat(path.join(root, "checktrail.json"));
+        if (!entry.isFile() || entry.isSymbolicLink())
+            throw new Error("checktrail.json must be a regular file, not a symlink or directory");
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function initialize(root, options = {}) {
+    root = await realpath(root);
+    const exists = await configurationExists(root);
+    const { source, plan } = await createPlan(root);
+    const result = {
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        status: "preview",
+        configuration: null,
+        unresolved: [],
+        executionEnabled: false,
+    };
+    if (exists) {
+        if (options.selections?.length)
+            throw new Error("Existing configuration is preserved; edit its policy explicitly to change checks");
+        return { ...result, status: "preserved" };
+    }
+    const selected = new Map();
+    for (const selection of options.selections ?? []) {
+        if (selected.has(selection.path))
+            throw new Error("Duplicate selection path");
+        if (!selection.checks.length ||
+            new Set(selection.checks).size !== selection.checks.length)
+            throw new Error("Selections require nonempty, unique check IDs");
+        selected.set(selection.path, selection.checks);
+    }
+    for (const selectedPath of selected.keys())
+        if (!plan.projects.some((project) => project.path === selectedPath))
+            throw new Error("Selection does not match a discovered project path");
+    const grouped = new Map();
+    for (const project of plan.projects) {
+        const registered = adapters.find((adapter) => adapter.id === project.adapter).checks;
+        const requested = selected.get(project.path);
+        let ids = requested?.filter((id) => registered.includes(id));
+        if (!requested) {
+            ids = plan.checks
+                .filter((check) => check.project === project.path &&
+                check.adapter === project.adapter &&
+                registered.includes(check.id))
+                .map((check) => check.id);
+            if (project.adapter === "python")
+                ids = [];
+            if (project.adapter === "javascript") {
+                const manifest = JSON.parse(await readProjectFile(root, path.posix.join(project.path, "package.json")));
+                const runners = {
+                    "node --test": "javascript.node-test",
+                    "vitest run": "javascript.vitest",
+                    jest: "javascript.jest",
+                    "playwright test": "javascript.playwright",
+                };
+                const script = manifest?.scripts?.test;
+                ids =
+                    typeof script === "string" && Object.hasOwn(runners, script)
+                        ? [runners[script]]
+                        : [];
+            }
+        }
+        if (!ids?.length ||
+            plan.checks.some((check) => check.project === project.path &&
+                check.adapter === project.adapter &&
+                check.kind === "unsupported")) {
+            result.unresolved.push({
+                path: project.path,
+                adapter: project.adapter,
+                choices: [...registered],
+            });
+            continue;
+        }
+        const candidates = await checksFor(source, project, ids);
+        if (ids.some((id) => !candidates.some((check) => check.id === id)))
+            throw new Error("Selected check is inapplicable to the discovered project");
+        const checks = grouped.get(project.path) ?? new Set();
+        for (const id of ids)
+            checks.add(id);
+        grouped.set(project.path, checks);
+    }
+    for (const [selectedPath, ids] of selected)
+        if (ids.some((id) => !grouped.get(selectedPath)?.has(id)))
+            throw new Error("Selected check is unknown or inapplicable");
+    if (!plan.projects.length || result.unresolved.length)
+        return { ...result, status: "needs-selection" };
+    result.configuration = configSchema.parse({
+        schemaVersion: 1,
+        projects: [...grouped].map(([projectPath, checks]) => ({
+            path: projectPath,
+            checks: [...checks].sort(),
+        })),
+    });
+    if (!options.write)
+        return result;
+    if ((await inventory(root)).fingerprint !== source.fingerprint)
+        throw new Error("Project changed during setup; review a fresh preview");
+    const temporary = await mkdtemp(path.join(root, ".checktrail-init-"));
+    try {
+        const staged = path.join(temporary, "checktrail.json");
+        await writeFile(staged, `${JSON.stringify(result.configuration, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        // An exclusive link publishes complete bytes without replacing a concurrent writer.
+        await link(staged, path.join(root, "checktrail.json"));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return { ...result, status: "created" };
+}
+async function executableAvailable(executable, cwd, searchPath) {
+    const candidates = executable.includes("/") || path.isAbsolute(executable)
+        ? [path.resolve(cwd, executable)]
+        : searchPath
+            .split(path.delimiter)
+            .map((directory) => path.resolve(cwd, directory, executable));
+    for (const candidate of candidates) {
+        try {
+            if (!(await stat(candidate)).isFile())
+                continue;
+            await access(candidate, constants.X_OK);
+            return true;
+        }
+        catch {
+            /* Other PATH entries may provide the executable. */
+        }
+    }
+    return false;
+}
+export async function diagnose(root, options = {}) {
+    const issues = [];
+    const result = {
+        schemaVersion: 1,
+        engineVersion: VERSION,
+        status: "attention-required",
+        validationPerformed: false,
+        projects: 0,
+        checks: 0,
+        issues,
+        unverified: [
+            "Tool versions and runtime compatibility",
+            "Importable modules and runtime services",
+            "Validation results; run with explicit project trust",
+        ],
+    };
+    const add = (issue) => {
+        const summary = { ...issue };
+        delete summary.project;
+        delete summary.detail;
+        issues.push(options.detailed ? issue : summary);
+    };
+    if (process.platform === "win32")
+        add({ code: "unsupported-platform" });
+    try {
+        root = await realpath(root);
+        await configurationExists(root);
+        const { plan } = await createPlan(root, {
+            ...(options.externalAdapters
+                ? { externalAdapters: options.externalAdapters }
+                : {}),
+            ...(options.policyOverlay
+                ? { policyOverlay: options.policyOverlay }
+                : {}),
+            ...(options.environment ? { environment: options.environment } : {}),
+        });
+        result.projects = plan.projects.length;
+        result.checks = plan.checks.length;
+        if (!plan.checks.length)
+            add({ code: "empty-plan" });
+        for (const project of plan.projects)
+            if (!plan.checks.some((check) => check.project === project.path && check.adapter === project.adapter))
+                add({
+                    code: "unselected-project",
+                    project: project.path,
+                    adapter: project.adapter,
+                });
+        for (const check of plan.checks) {
+            const context = {
+                check: check.id,
+                adapter: check.adapter,
+                project: check.project,
+            };
+            if (check.unavailableReason)
+                add({
+                    ...context,
+                    code: "unavailable-check",
+                    detail: check.unavailableReason,
+                });
+            const commands = [...check.commands];
+            for (const tool of check.tools ?? []) {
+                if (tool.source === "version-command")
+                    commands.push(tool.command);
+                else if (tool.source === "package-metadata") {
+                    const identity = await identifyTool(root, tool, async () => {
+                        throw new Error("Doctor must not execute version probes");
+                    });
+                    if (identity.status !== "identified")
+                        add({
+                            ...context,
+                            code: "package-metadata",
+                            detail: `Missing or invalid package metadata: ${tool.name}`,
+                        });
+                }
+            }
+            const wrapped = check.adapter === "jvm"
+                ? ["java"]
+                : check.adapter === "dotnet"
+                    ? ["dotnet"]
+                    : check.id === "infrastructure.actionlint"
+                        ? ["actionlint"]
+                        : [];
+            for (const executable of wrapped)
+                commands.push({ executable, args: [], cwd: check.project });
+            const checked = new Set();
+            for (const command of commands) {
+                const searchPath = command.env?.PATH ??
+                    (check.environment?.includes("PATH")
+                        ? options.environment?.PATH
+                        : undefined) ??
+                    process.env.PATH ??
+                    "/usr/bin:/bin";
+                const cwd = path.resolve(root, command.cwd);
+                const key = JSON.stringify([command.executable, cwd, searchPath]);
+                if (checked.has(key))
+                    continue;
+                checked.add(key);
+                if (!(await executableAvailable(command.executable, cwd, searchPath)))
+                    add({
+                        ...context,
+                        code: "missing-executable",
+                        detail: `Executable unavailable or not executable: ${command.executable}`,
+                    });
+            }
+        }
+    }
+    catch (error) {
+        add({
+            code: "configuration-error",
+            detail: error instanceof Error ? error.message : "Cannot inspect project",
+        });
+    }
+    result.status = issues.length ? "attention-required" : "no-static-blockers";
+    return result;
+}
+export const mcpClients = [
+    "codex",
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "vscode",
+];
+export async function mcpConfiguration(root, client) {
+    if (!mcpClients.includes(client))
+        throw new Error("Unknown MCP client");
+    root = await realpath(root);
+    if (!(await stat(root)).isDirectory())
+        throw new Error("MCP root must be a directory");
+    if (root.includes("${"))
+        throw new Error("MCP root contains client variable syntax; choose a path without ${");
+    const server = {
+        command: "npx",
+        args: [
+            "--yes",
+            "--ignore-scripts",
+            `@stsepelin/checktrail@${VERSION}`,
+            "serve",
+            "--root",
+            root,
+        ],
+    };
+    return {
+        client,
+        executionEnabled: false,
+        format: client === "codex" ? "toml" : "json",
+        configuration: client === "codex"
+            ? `[mcp_servers.checktrail]\ncommand = "npx"\nargs = ${JSON.stringify(server.args)}\n`
+            : `${JSON.stringify(client === "vscode" ? { servers: { checktrail: { type: "stdio", ...server } } } : { mcpServers: { checktrail: server } }, null, 2)}\n`,
+    };
+}

package/dist/src/types.d.ts

@@ -1,6 +1,6 @@
 import type { ExternalIdentity } from "./external-adapter.js";
 import type { RuntimeInventory } from "./runtime-inventory.js";
-export declare const VERSION = "0.1.0-alpha.1";
+export declare const VERSION = "0.1.0-alpha.2";
 export declare const PARSERS: readonly ["vue-router-json", "nuxt-json", "exit", "empty", "node-events", "unittest", "go-scope-test", "go-scope-analysis", "golangci-json", "staticcheck-json", "go-json", "typescript-build-json", "tsc-files", "eslint-json", "vitest-json", "playwright-json", "jest-json", "pytest-json", "fastapi-json", "django-json", "laravel-json", "rust-json", "clang-json", "java-json", "dotnet-json", "actionlint-json", "external-json", "ruby-syntax", "silent-syntax", "ruff-json", "mypy-json", "phpstan-json", "phpunit-junit", "pint-json"];
 export type Status = "passed" | "failed" | "unavailable" | "skipped" | "error" | "inconclusive";
 export type Outcome = "passed" | "failed" | "incomplete";

package/dist/src/types.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.1.0-alpha.1";
+export const VERSION = "0.1.0-alpha.2";
 export const PARSERS = [
     "vue-router-json",
     "nuxt-json",

package/docs/ACCEPTANCE.md

@@ -5,14 +5,14 @@ verification. It does not replace the plan or promote an unverified capability.
 Local implementation, local native evidence, hosted CI and publication are
 separate states. Follow the linked evidence for tested versions and limits.
 
-| Milestone                         | Implemented scope and evidence                                                                                                                                                                                                                                                                                                                                                                                                          | Open acceptance work                                                                                                                                                                                                                                                |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| M0: public contracts              | Original public fixtures, MIT license, security/contribution guidance, schemas, explicit package allowlist, dependency notices and CI definitions. `STATUS.md`, `SECURITY.md`, `RELEASE.md`.                                                                                                                                                                                                                                            | Public source is published and all hosted jobs passed at `52ba415`. The preview candidate still requires its own release commit, CI and publication verification.                                                                                                   |
-| M1: executable foundation         | Shared CLI/library/MCP engine, bounded inventory/runner, startup trust, native Node/Python/Go/PHP profiles, protocol and lifecycle regressions. `ARCHITECTURE.md`, `STATUS.md`, `MCP-COMPATIBILITY.md`. Fresh installed application-client profiles now have evidence in `CLIENTS.md`.                                                                                                                                                  | Application-client coverage beyond the named profiles. PHP remains unavailable when the consumer has no prepared runtime.                                                                                                                                           |
-| M2: practical language validation | Explicit JS/TS, Python, Go and PHP native tool profiles, structured diagnostics/test evidence, versions, environments, workspace selection, scope accounting, SARIF/JUnit and finding ratchets. `LANGUAGES.md`, adapter documents, `WORKSPACES.md`, `FINDING-POLICY.md`, `NATIVE-CI.md`.                                                                                                                                                | Hosted toolchain profiles passed at `52ba415`. Wider tool versions/framework configurations must be promoted separately; detection is not execution support.                                                                                                        |
-| M3: framework/contracts           | Native Laravel, Vue Router/Nuxt, Django/FastAPI assembly projections; imported runtime comparison, explicit architecture boundaries, producer/consumer schemas and a built package consumer. `RUNTIME-INVENTORY.md`, framework documents, `CONTRACTS.md`, `ARCHITECTURE-POLICY.md`, `examples/package-contract/README.md`.                                                                                                              | Broader native semantics/import collection and live service integration are not implemented. Synthetic evidence does not establish equivalent results in a private application; private integration feedback must remain private.                                   |
-| M4: ecosystem/distribution        | Bounded Rust, Java, C#, Ruby, Swift, Clang and actionlint profiles; trusted external adapters, pinned data-only pack distribution, fresh offline package checks, production notice audit, measured performance and unpublished registry metadata. `LANGUAGES.md`, `EXTERNAL-ADAPTERS.md`, `PACK-DISTRIBUTION.md`, `PERFORMANCE.md`, `RELEASE.md`.                                                                                       | Concrete preview release authorization and verification. Windows execution and the unimplemented subsequent integrations in `LANGUAGES.md` remain unsupported. Runtime/container/development dependency provenance is broader than the production npm notice audit. |
-| M5: measured assistance           | Advisory guidance, bounded Node mutation experiments, explicit-graph impact measurements, optional local/model review exchange, durable library task storage/worker, development evaluation and externally authored ESLint and Ruff integration cohorts. `GUIDANCE.md`, `MUTATIONS.md`, `IMPACT-MEASUREMENT.md`, `REVIEW-EXCHANGE.md`, `VALIDATION-TASKS.md`, `EVALUATION.md`, `EXTERNAL-EVALUATION.md`, `EXTERNAL-RUFF-EVALUATION.md`. | Standard MCP Tasks wire integration; wider held-out rule-family/review evidence, prior-workflow comparison and representative cost/latency measurement. No general equal-or-better review-quality claim is supported.                                               |
+| Milestone                         | Implemented scope and evidence                                                                                                                                                                                                                                                                                                                                                                                                          | Open acceptance work                                                                                                                                                                                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| M0: public contracts              | Original public fixtures, MIT license, security/contribution guidance, schemas, explicit package allowlist, dependency notices and CI definitions. `STATUS.md`, `SECURITY.md`, `RELEASE.md`.                                                                                                                                                                                                                                            | Public source and npm alpha.1 are published. Hosted CI passed at `bfc8cc4`; alpha.2 requires its own release commit, CI and publication verification.                                                                                                                  |
+| M1: executable foundation         | Shared CLI/library/MCP engine, bounded inventory/runner, startup trust, native Node/Python/Go/PHP profiles, protocol and lifecycle regressions. `ARCHITECTURE.md`, `STATUS.md`, `MCP-COMPATIBILITY.md`. Fresh installed application-client profiles now have evidence in `CLIENTS.md`.                                                                                                                                                  | Application-client coverage beyond the named profiles. PHP remains unavailable when the consumer has no prepared runtime.                                                                                                                                              |
+| M2: practical language validation | Explicit JS/TS, Python, Go and PHP native tool profiles, structured diagnostics/test evidence, versions, environments, workspace selection, scope accounting, SARIF/JUnit and finding ratchets. `LANGUAGES.md`, adapter documents, `WORKSPACES.md`, `FINDING-POLICY.md`, `NATIVE-CI.md`.                                                                                                                                                | Hosted toolchain profiles passed at `52ba415`. Wider tool versions/framework configurations must be promoted separately; detection is not execution support.                                                                                                           |
+| M3: framework/contracts           | Native Laravel, Vue Router/Nuxt, Django/FastAPI assembly projections; imported runtime comparison, explicit architecture boundaries, producer/consumer schemas and a built package consumer. `RUNTIME-INVENTORY.md`, framework documents, `CONTRACTS.md`, `ARCHITECTURE-POLICY.md`, `examples/package-contract/README.md`.                                                                                                              | Broader native semantics/import collection and live service integration are not implemented. Synthetic evidence does not establish equivalent results in a private application; private integration feedback must remain private.                                      |
+| M4: ecosystem/distribution        | Bounded Rust, Java, C#, Ruby, Swift, Clang and actionlint profiles; trusted external adapters, pinned data-only pack distribution, fresh offline package checks, production notice audit, measured performance and unpublished registry metadata. `LANGUAGES.md`, `EXTERNAL-ADAPTERS.md`, `PACK-DISTRIBUTION.md`, `PERFORMANCE.md`, `RELEASE.md`.                                                                                       | Alpha.2 release verification and MCP Registry registration. Windows execution and the unimplemented subsequent integrations in `LANGUAGES.md` remain unsupported. Runtime/container/development dependency provenance is broader than the production npm notice audit. |
+| M5: measured assistance           | Advisory guidance, bounded Node mutation experiments, explicit-graph impact measurements, optional local/model review exchange, durable library task storage/worker, development evaluation and externally authored ESLint and Ruff integration cohorts. `GUIDANCE.md`, `MUTATIONS.md`, `IMPACT-MEASUREMENT.md`, `REVIEW-EXCHANGE.md`, `VALIDATION-TASKS.md`, `EVALUATION.md`, `EXTERNAL-EVALUATION.md`, `EXTERNAL-RUFF-EVALUATION.md`. | Standard MCP Tasks wire integration; wider held-out rule-family/review evidence, prior-workflow comparison and representative cost/latency measurement. No general equal-or-better review-quality claim is supported.                                                  |
 
 ## Remaining work that can proceed locally
 
@@ -43,11 +43,12 @@ run. The local worker/store are available independently; standard Tasks must sta
 unadvertised until routing and the integrated wire/lifecycle suite pass. See
 `MCP-COMPATIBILITY.md` for the reproduction and upstream issue.
 
-The public repository and initial commit `60131d6` are available on `main`.
-All 13 hosted jobs passed at `52ba415`, recorded in `NATIVE-CI.md`.
-That result identifies the source baseline, not an unpublished preview package. Package publishing, GitHub releases and registry
-registration have not been performed. The repository's explicit-action
-requirements still apply. `RELEASE.md` defines the concrete
+The public repository and npm preview `0.1.0-alpha.1` are published. The
+[hosted run at bfc8cc4](https://github.com/stsepelin/checktrail/actions/runs/35585998184)
+passed all jobs. Alpha.2 adds [setup commands](ONBOARDING.md); it requires its own
+release CI and publication. GitHub releases and MCP Registry registration remain
+pending. The repository's explicit-action requirements still apply.
+`RELEASE.md` defines the concrete
 candidate checks and the authorization sequence; a local green run does not
 replace external acceptance.
 

package/docs/ARCHITECTURE.md

@@ -58,7 +58,9 @@ pass by a parser. Source changes during execution invalidate a green result.
 
 Use bounded process output and timeouts, terminate the process group on supported
 POSIX hosts, and propagate cancellation. No automatic dependency installation,
-source rewriting, infrastructure startup, deployment or repository mutation.
+source rewriting, infrastructure startup or deployment. The explicit `init --write`
+setup command can create a new `checktrail.json`; it preserves existing
+configuration and grants no execution. See [ONBOARDING.md](ONBOARDING.md).
 Executed project code still has the process user's privileges; this is not a
 sandbox. Tests may modify files or access networks and must be trusted accordingly.
 

package/docs/INSTALLATION.md

@@ -1,14 +1,19 @@
 # Install the preview
 
-The first preview version is `0.1.0-alpha.1`, intended for npm's `next` tag.
-Check the [npm package page](https://www.npmjs.com/package/@stsepelin/checktrail)
-for availability. The registry commands below require that version to be published;
-before publication, use the source checkout or a reviewed local tarball.
+The published preview is `0.1.0-alpha.1` on
+[npm](https://www.npmjs.com/package/@stsepelin/checktrail).
+Use the exact version below. The registry currently assigns both `next` and
+`latest` to that preview; `latest` is not a stable-release guarantee.
+The alpha.2 candidate adds [project setup and diagnosis](ONBOARDING.md) and is
+available from source or a reviewed candidate tarball until published.
 
 Use Node.js 22 or newer on macOS or Linux. Windows execution is not supported.
 Install each project's compilers, linters and test runners separately; Checktrail
 does not download them. Missing tools produce incomplete results.
 
+For agent workflows, see [installing skills with `npx skills`](SKILLS.md).
+Skills install separately from the engine and MCP configuration.
+
 ## CLI
 
 Install the exact version once:
@@ -84,7 +89,7 @@ Validation uses asynchronous calls and supports cancellation. Standard MCP Tasks
 is not advertised; the durable worker is a separate library API. See
 [client coverage](CLIENTS.md) and [MCP compatibility](MCP-COMPATIBILITY.md).
 
-## Before npm publication
+## Source checkout or unpublished candidate
 
 Build the public source checkout:
 

package/docs/LANGUAGES.md

@@ -1,5 +1,9 @@
 # Language and ecosystem roadmap
 
+The alpha.2 candidate's [setup guide](ONBOARDING.md) describes conservative
+per-language configuration proposals and static tool diagnosis. Setup does not
+extend the execution capabilities or native evidence listed below.
+
 Capability levels are discovery, planning, execution, structured evidence,
 semantic rules, and integration validation. None implies the next. This file's
 initial scope column describes the experimental implementation. Node, Python,

package/docs/ONBOARDING.md

@@ -0,0 +1,128 @@
+# Project setup
+
+These commands are new in the unpublished `0.1.0-alpha.2` candidate. Use the
+source checkout or a reviewed candidate tarball, with Node.js 22+ on macOS/Linux.
+
+## Preview and create a policy
+
+```sh
+checktrail init --root "$PWD"
+checktrail init --root "$PWD" --write
+checktrail doctor --root "$PWD" --detailed
+```
+
+`init` returns JSON with a proposed `configuration`. The preview changes nothing.
+`--write` creates `checktrail.json` only when every discovered ecosystem has a
+selected supported check, publishing complete contents without replacing an
+existing file. A valid existing policy returns `preserved`, retaining its bytes,
+packs, environment requirements and workspace graph. Invalid policies, directories
+and symlinks are errors and remain untouched. There is no overwrite option.
+
+The preview includes relative project paths, groups ecosystems sharing a directory
+and preserves nested project boundaries. It does not infer workspace dependencies,
+grant execution, install tools, run scripts or import project code. Use `doctor`
+and the detailed plan to inspect prerequisites before running validation.
+
+| Ecosystem                          | Initial selection                                                                                                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| JavaScript / TypeScript            | Exact test scripts `node --test`, `vitest run`, `jest`, or `playwright test`; other commands need selection. Linters and type checks require explicit selection. |
+| Python                             | Explicit runner/check selection required; a manifest cannot identify a test framework.                                                                           |
+| Go                                 | Existing format, vet and test defaults.                                                                                                                          |
+| PHP                                | Syntax only; tests and analysis require explicit selection.                                                                                                      |
+| Rust, Java, C#, Ruby, Swift, C/C++ | Existing bounded adapter defaults; profiles, tools and dependencies still need preparation.                                                                      |
+| Infrastructure                     | GitHub Actions checking where applicable; other infrastructure remains an unresolved gap.                                                                        |
+
+`needs-selection` exits `2`, returns no partial configuration and writes nothing.
+Its `unresolved` entries list paths, ecosystems and registered choices; those
+choices do not promise tools are installed or applicable to every source file.
+Repeated `--check PATH#CHECK_ID` arguments select the complete check set for a path:
+
+```sh
+checktrail init --root "$PWD" --check '.#python.pytest' --check '.#python.ruff'
+checktrail init --root "$PWD" --check '.#python.pytest' --check '.#python.ruff' --write
+```
+
+Paths must exactly match discovered roots. For a polyglot directory, include
+checks for every discovered ecosystem there. Unmentioned paths keep defaults.
+Unknown and duplicate IDs are errors. Setup never silently drops unsupported
+ecosystems. External adapters and private overlays are supported by planning and
+diagnosis but are not generated by `init`.
+
+## Diagnose setup without execution
+
+`doctor` reuses the planner. It reports invalid configuration, unavailable checks,
+missing/non-executable programs, invalid JS tool metadata, missing required
+environment, empty plans, unsupported platforms and ecosystems omitted by policy.
+An intentionally narrowed policy can therefore produce `unselected-project`.
+
+Executable checks use the effective PATH and file permissions. Diagnosis never
+runs version commands, imports modules, boots frameworks or runs tests. Prepare
+native tools and activate Python environments on the PATH used for validation.
+
+Output always includes `validationPerformed: false` and unverified runtime
+properties. `no-static-blockers` exits `0`; `attention-required` exits `2`.
+Neither means validation passed. Tool compatibility, importable modules, services
+and execution results still need a trusted `run`.
+
+Summary output omits paths and raw errors. `--detailed` adds paths and diagnostic
+details that can contain absolute paths. Supported options include
+`--policy-overlay`, pinned `--adapter` references and `--allow-env NAME`.
+Environment values are not printed. Git selection and execution flags are rejected.
+
+## Generate MCP configuration
+
+```sh
+checktrail mcp-config --root "$PWD" --client codex
+checktrail mcp-config --root "$PWD" --client claude-code
+checktrail mcp-config --root "$PWD" --client claude-desktop
+checktrail mcp-config --root "$PWD" --client cursor
+checktrail mcp-config --root "$PWD" --client vscode
+```
+
+Output is JSON containing `format` and a `configuration` string. Merge the decoded
+string's server entry into the appropriate client configuration. The generator
+never opens or overwrites client files. Do not redirect the JSON envelope over
+an existing configuration.
+
+| Client         | Generated format / location                                   |
+| -------------- | ------------------------------------------------------------- |
+| Codex          | TOML `mcp_servers.checktrail`; Codex `config.toml`.           |
+| Claude Code    | JSON `mcpServers.checktrail`; project `.mcp.json`.            |
+| Claude Desktop | JSON `mcpServers.checktrail`; developer MCP configuration.    |
+| Cursor         | JSON `mcpServers.checktrail`; `.cursor/mcp.json`.             |
+| VS Code        | JSON `servers.checktrail`, `type: stdio`; `.vscode/mcp.json`. |
+
+Snippets capture the canonical absolute root and pin the generating engine version
+in `npx --yes --ignore-scripts @stsepelin/checktrail@VERSION serve`. Execution
+and detailed output remain disabled; client trust settings still apply. Roots
+containing `${` are rejected because client interpolation could change the root.
+
+Generation needs no network; starting npx may download the pinned package. The
+version must be published first. For an unpublished candidate, use its installed
+absolute `checktrail` executable with `serve --root /absolute/project` instead.
+After reviewing an update, regenerate/merge the entry and restart the client.
+Updating a global CLI does not change an npx version pin.
+
+Formats follow official [Codex](https://developers.openai.com/codex/mcp/),
+[Claude Code](https://code.claude.com/docs/en/mcp),
+[Cursor](https://cursor.com/docs/mcp), and
+[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
+documentation. Generation is not proof of a client connection; [CLIENTS.md](CLIENTS.md)
+records tested application profiles and limits.
+
+## Upgrade and rollback verification
+
+Build and prepare the npm cache for both reviewed artifacts, then run:
+
+```sh
+node scripts/verify-package-upgrade.mjs /absolute/baseline.tgz /absolute/candidate.tgz
+```
+
+The verifier installs baseline → candidate → baseline into one isolated consumer
+offline with lifecycle scripts disabled. Each stage checks the CLI version,
+planning, a native Node test, MCP planning and denied untrusted execution. Project
+source, policy and existing client configuration must remain byte-identical.
+The candidate must preserve the policy through `init --write`, diagnose it, and
+import the baseline report through SARIF export. Output records artifact hashes
+and measured stages. This exercises a synthetic Node workflow, not migration of
+every language/tool profile.

package/docs/RELEASE.md

@@ -1,12 +1,20 @@
 # Release preparation
 
 The source is public at [stsepelin/checktrail](https://github.com/stsepelin/checktrail);
-the first preview is `0.1.0-alpha.1`. `server.json` describes the
-intended `io.github.stsepelin/checktrail` MCP registry identity and the matching
-`@stsepelin/checktrail` npm package. The npm and registry names are proposed
-metadata, not evidence of a published package or registry entry. Package publishing
-is configured for public access on npm's `next` tag. No credentials or automatic
-publishing workflow are stored in this repository.
+`@stsepelin/checktrail@0.1.0-alpha.1` is published on npm. Its downloaded artifact
+matched the reviewed tarball with SHA-256
+`84003e184805b6c5362c0801c702a72e415040ae5142fcd70f01eb9758637d04`.
+Fresh registry installation, CLI and MCP startup were verified. The alpha.2
+candidate adds [setup and diagnosis](ONBOARDING.md); it is not yet published.
+`server.json` describes the intended `io.github.stsepelin/checktrail` MCP Registry
+identity with the candidate's matching npm version. Registry registration remains
+pending. No credentials or automatic publishing workflow are stored here.
+
+Publication is configured for npm's `next` tag. After alpha.1 publication, the
+registry assigned both `next` and `latest` to that preview; attempts to remove
+`latest` returned HTTP 400. The cause is unresolved. Use exact versions and
+resolve the tag policy before publishing another candidate; do not treat `latest`
+as evidence of a stable release or republish an existing version.
 
 ## Prepared artifacts
 
@@ -24,8 +32,8 @@ publishing workflow are stored in this repository.
   loads the installed metadata and verifies its actual startup command.
 - CI definitions cover the host suite and prepared native profiles. Local
   containers and package checks are evidence only for the environments actually
-  exercised. All 13 hosted jobs passed at source baseline `52ba415`; the preview
-  release commit requires its own run. The local Claude Code health/discovery and
+  exercised. The [hosted run at bfc8cc4](https://github.com/stsepelin/checktrail/actions/runs/35585998184)
+  passed all jobs; the alpha.2 release commit requires its own run. The local Claude Code health/discovery and
   Codex direct app-server profiles have fresh-install evidence in `CLIENTS.md`.
 
 The metadata follows the official registry
@@ -61,7 +69,7 @@ After explicit approval and npm authentication for the `@stsepelin` scope, publi
 the approved file, not a newly packed working tree:
 
 ```sh
-npm publish /absolute/path/stsepelin-checktrail-0.1.0-alpha.1.tgz \
+npm publish /absolute/path/stsepelin-checktrail-0.1.0-alpha.2.tgz \
   --tag next --access public --ignore-scripts --registry=https://registry.npmjs.org
 ```
 
@@ -93,6 +101,8 @@ GitHub private vulnerability reporting is enabled. Use the channel linked in
    Run the corresponding native verification helpers for every advertised profile.
    Record actual tool/platform results and explicit skips. Repeat registry schema
    validation against its pinned bytes.
+   Run `scripts/verify-package-upgrade.mjs` with the reviewed previous and candidate
+   tarballs to verify offline upgrade, policy/report compatibility and rollback.
 3. Inspect the exact tarball and its SHA-256, its source revision, dependency/notice
    report, package allowlist, public examples and documentation. The smoke helper
    compares repeated packing of the same checkout and tests a fresh offline install;

package/docs/SKILLS.md

@@ -0,0 +1,123 @@
+# Install agent skills with npx skills
+
+Checktrail provides portable workflows for setup, validation and review:
+
+| Skill                 | Use it for                                                                     |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `checktrail-setup`    | Configure project roots, select supported language checks and connect MCP      |
+| `checktrail-validate` | Run authorized checks and distinguish passed, failed and incomplete evidence   |
+| `checktrail-review`   | Review code and test adequacy using validation evidence and advisory questions |
+
+Each skill is self-contained in `skills/<name>/SKILL.md` and follows the
+[Agent Skills format](https://agentskills.io/specification). The
+[Vercel skills CLI](https://github.com/vercel-labs/skills) installs these folders
+from GitHub. No Checktrail plugin or separate skills registry registration is
+required for installation by repository URL.
+
+## Install
+
+These GitHub commands require the `skills/` directory to be present on the public
+repository's default branch. For an unpublished checkout, use the local command
+below. Listing the remote source first verifies what is available:
+
+```sh
+npx skills add stsepelin/checktrail --list
+npx skills add stsepelin/checktrail
+```
+
+The interactive installer lets you choose skills and target agents. For an
+explicit project installation, run from the repository where you want to use
+Checktrail:
+
+```sh
+npx skills add stsepelin/checktrail \
+  --skill checktrail-setup checktrail-validate checktrail-review \
+  --agent codex claude-code cursor
+```
+
+Choose only the agents you use. Add `--global` for a personal installation shared
+across projects, or `--yes` when deliberately skipping installer prompts. The
+default installation uses project directories; it does not configure an MCP server.
+Use `--copy` if independent copies are preferable to the installer's default links.
+
+To install from a local checkout before pushing, substitute its absolute path:
+
+```sh
+npx skills add /absolute/path/to/checktrail --skill checktrail-validate --agent codex
+```
+
+The CLI's agent target names are installer options, not evidence that Checktrail
+has been tested end-to-end in every editor. See [client coverage](CLIENTS.md).
+Reload skills or start a new session as required by the selected agent. Example
+requests are "Set up Checktrail for this repository", "Validate these changes
+with Checktrail", and "Review this diff using Checktrail evidence".
+
+## Install the engine separately
+
+`npx skills` installs instructions. It does not install the npm engine, native
+language tools, an MCP server, or execution permissions. The skills support an
+existing MCP connection or the CLI, including the published preview:
+
+```sh
+npx --yes --ignore-scripts @stsepelin/checktrail@0.1.0-alpha.1 plan --root /absolute/project
+```
+
+Use Node.js 22+ on macOS or Linux. See [installation](INSTALLATION.md) for persistent
+CLI installation, MCP registration and operator-controlled execution. Skills do
+not expand native language coverage, grant trust, or replace required CI checks.
+
+## Update and remove
+
+For GitHub-installed project skills, update just Checktrail's workflows:
+
+```sh
+npx skills update checktrail-setup checktrail-validate checktrail-review --project
+```
+
+Use `--global` instead of `--project` for a global installation. Updates replace
+installed instructions; keep project-specific policy in your project's own files.
+Retain and review the project installation's `skills-lock.json` and file changes.
+For local-path installations, re-run `skills add` against the updated checkout.
+
+The installer version used for local verification is `skills@1.7.0`. It aliases
+`skills check` to `skills update`; do not use `check` as a read-only update probe.
+Use `npx skills list` to inspect installed skills. Pin the installer itself with
+`npx skills@1.7.0` when reproducing the installation checks.
+
+Skill updates and engine updates are separate. The skills declare the Checktrail
+version they target. To update the engine, deliberately select a compatible npm
+version and restart the MCP process. Updating skills never changes its root,
+execution grant or output disclosure settings. For a reproducible skill revision,
+install from a reviewed GitHub tree URL containing a commit SHA and the selected
+skill path; re-add that same revision to roll back. Do not treat following a branch
+as an immutable pin.
+
+Remove the project skills with:
+
+```sh
+npx skills remove checktrail-setup checktrail-validate checktrail-review
+```
+
+Add `--global` for a global removal. This removes skills, not the separately
+installed engine or MCP configuration.
+
+## Verification boundaries
+
+Local checks exercise discovery, selective installation, copy/link destinations,
+file integrity, reinstallation from an updated local source and removal in
+temporary projects. They do not modify personal agent installations. Skill format
+validation does not prove model behavior or improved review quality. Installation
+from the public GitHub source and remote update verification require the changes
+to be pushed; a local installation is not evidence of either.
+
+Reproduce the installation checks from the Checktrail checkout:
+
+```sh
+npm install --prefix .checktrail/skills-tools --ignore-scripts --no-audit --no-fund \
+  --package-lock=false --save-exact skills@1.7.0
+node scripts/verify-skills-install.mjs .checktrail/skills-tools/node_modules/skills/bin/cli.mjs
+```
+
+The helper uses temporary project and installer-state directories, exercises the
+real installer, and removes its fixtures afterward. It does not run a model,
+register MCP, install global skills, or invoke remote skill updates.

package/docs/STATUS.md

@@ -3,12 +3,19 @@
 This is an experimental foundation with public source at
 [stsepelin/checktrail](https://github.com/stsepelin/checktrail).
 Check the [installation guide](INSTALLATION.md) for package availability and setup.
-All 13 hosted jobs passed at `52ba415`; the exact run and earlier cache/path
-failures are recorded in `NATIVE-CI.md`. The `0.1.0-alpha.1` preview changes
-release metadata and documentation; its publication is a separate gate.
+The `0.1.0-alpha.1` preview is published on npm. The newer
+[hosted run at bfc8cc4](https://github.com/stsepelin/checktrail/actions/runs/35585998184)
+passed all jobs; earlier toolchain evidence remains in `NATIVE-CI.md`.
+The alpha.2 candidate adds setup commands and requires its own release CI and
+publication. MCP Registry registration remains pending.
 
 ## Implemented
 
+- Alpha.2 candidate: conservative multi-language `init`, execution-free `doctor`,
+  and version-pinned MCP configuration output for Codex, Claude Code/Desktop,
+  Cursor and VS Code. Existing files are preserved. See [ONBOARDING.md](ONBOARDING.md)
+  for scope, ambiguity handling and package upgrade/rollback verification.
+
 - Exact required-test accounting across prepared CI language profiles and native
   container helpers, including dedicated Ruby/Swift jobs. Skipped, missing,
   duplicate, TODO or failing cases cannot satisfy these profiles. Hosted profiles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stsepelin/checktrail",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "mcpName": "io.github.stsepelin/checktrail",
   "description": "Local code validation with execution evidence, a CLI, and MCP tools.",
   "type": "module",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.stsepelin/checktrail",
   "title": "Checktrail",
   "description": "Local code validation with explicit execution trust and evidence of what actually ran.",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "repository": {
     "url": "https://github.com/stsepelin/checktrail",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@stsepelin/checktrail",
-      "version": "0.1.0-alpha.1",
+      "version": "0.1.0-alpha.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"