@phyzess/pappra 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/app/init.js

@@ -7,7 +7,7 @@ import { INIT_CHOICES_SCHEMA, initPlanSchema, parseInitChoices, } from '../schem
 import { machineConfigSchema } from '../schemas/machine.js';
 import { isExternalRepositoryPath, isPathInside, isPortableRelativePath, normalizePortableRelativePath, resolvePortableRelativePath, samePath, } from '../schemas/paths.js';
 import { WORKSPACE_SCHEMA, validateWorkspaceConfigSemantics, workspaceConfigSchema, } from '../schemas/workspace.js';
-import { getPackageInfo } from '../package-info.js';
+import { getPackageInfo, getPackageRoot } from '../package-info.js';
 import { spawnSync } from 'node:child_process';
 import { executableOnPath } from '../hosts/detect.js';
 import { HOST_SUPPORT } from '../hosts/integration/support.js';
@@ -17,7 +17,8 @@ import { discoverWorkspace, } from '../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../workspace/resolve.js';
 import { buildInitPlan } from '../install/plan.js';
 import { backupPath, ensureStatePathBoundary, readWorkspaceManifest, writeWorkspaceManifest, } from '../install/ownership.js';
-import { beginManagedApply, completeManagedApply, failManagedApply, recordManagedFile, } from '../install/apply.js';
+import { beginManagedApply, completeManagedApply, failManagedApply, recordManagedFile, updateMachineRuntime, } from '../install/apply.js';
+import { installRuntime, } from '../install/runtime.js';
 const workspaceConfigRelativePath = '.pappra/workspace.json';
 const machineConfigRelativePath = '.pappra/local/machine.json';
 function failure(status, code, message, diagnostics = [], nextAction = null) {
@@ -251,7 +252,7 @@ const derivedExcludes = [
     'test-results',
 ];
 const derivedValidationScripts = ['lint', 'typecheck', 'test'];
-function detectedHostVersion(command, pathEnv) {
+export function detectedHostVersion(command, pathEnv) {
     const executable = executableOnPath(command, pathEnv);
     if (executable === null)
         return null;
@@ -1440,3 +1441,81 @@ export async function applyInitPlan(bundle, options = {}) {
         };
     }
 }
+export async function bindAndRecordRuntime(root, installed) {
+    if (!installed.ok || installed.manifest === null) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: installed.diagnostics,
+        };
+    }
+    const updated = await updateMachineRuntime(root, installed.manifest);
+    if (!updated.ok) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: updated.diagnostics,
+        };
+    }
+    const followUp = await planWorkspaceInit({ root });
+    if (!followUp.ok) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: followUp.diagnostics,
+        };
+    }
+    if (followUp.bundle.plan.files.length > 0 ||
+        followUp.bundle.plan.externalActions.length > 0) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: [
+                {
+                    code: diagnosticCodes.initRuntimeSourceRequired,
+                    severity: 'error',
+                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
+                    source: 'init runtime',
+                    pointer: null,
+                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
+                },
+            ],
+        };
+    }
+    return {
+        ok: true,
+        completion: true,
+        runtime: installed,
+        diagnostics: [],
+    };
+}
+/**
+ * Converges the runtime binding by installing a durable copy of the package that
+ * is currently executing. Reusing an already verified copy is cheap: the install
+ * machinery short-circuits before packing.
+ */
+export async function ensureDefaultRuntime(root, targetVersion) {
+    const machine = await inspectMachineConfig(root);
+    const binding = machine.value?.runtime ?? null;
+    if (binding !== null && binding.version === targetVersion) {
+        const executable = await observePath(binding.executable);
+        if (executable.kind === 'file') {
+            return {
+                ok: true,
+                completion: true,
+                runtime: null,
+                diagnostics: [],
+            };
+        }
+    }
+    const installed = await installRuntime({
+        version: targetVersion,
+        source: { kind: 'self', path: getPackageRoot() },
+        packageName: getPackageInfo().name,
+    });
+    return bindAndRecordRuntime(root, installed);
+}

package/dist/app/onboard.d.ts

@@ -0,0 +1,60 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { HostName } from '../schemas/host.js';
+import type { InitChoices } from '../schemas/init.js';
+import { type InitContext, type InitPlanBundle } from './init.js';
+export type OnboardHostState = 'verified' | 'unverified' | 'unsupported' | 'missing';
+export interface OnboardHostPlan {
+    readonly host: HostName;
+    readonly command: string;
+    readonly detectedVersion: string | null;
+    readonly pinnedVersion: string;
+    readonly state: OnboardHostState;
+}
+export interface OnboardHostResult extends OnboardHostPlan {
+    readonly action: 'planned' | 'installed' | 'unchanged' | 'skipped' | 'failed';
+    readonly appliedFiles: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface OnboardPlan {
+    readonly context: InitContext;
+    readonly choices: InitChoices;
+    readonly bundle: InitPlanBundle;
+    readonly hosts: readonly OnboardHostPlan[];
+    readonly requestedHosts: readonly HostName[];
+}
+export interface OnboardResult {
+    readonly schema: 'pappra/onboard/1';
+    readonly ok: boolean;
+    readonly dryRun: boolean;
+    readonly workspaceRoot: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly operation: string;
+    }[];
+    readonly runtime: {
+        readonly version: string;
+        readonly status: string;
+    } | null;
+    readonly initComplete: boolean;
+    readonly hosts: readonly OnboardHostResult[];
+    readonly manualSteps: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface OnboardFailure {
+    readonly ok: false;
+    readonly reason: 'invalid' | 'needs_input' | 'unavailable' | 'failed';
+    readonly message: string;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function parseHostList(value: string | null): HostName[] | null;
+export declare function planOnboard(options: {
+    readonly root: string;
+    readonly choices?: InitChoices | null;
+    readonly hosts?: readonly HostName[] | null;
+    readonly pathEnv?: string;
+}): Promise<OnboardPlan | OnboardFailure>;
+export declare function applyOnboard(plan: OnboardPlan, options: {
+    readonly applyHosts: boolean;
+}): Promise<OnboardResult>;

package/dist/app/onboard.js

@@ -0,0 +1,259 @@
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { HOST_SUPPORT } from '../hosts/integration/support.js';
+import { exportHostPluginBundle } from '../hosts/integration/bundle-export.js';
+import { HostIntegrationService } from '../hosts/integration/service.js';
+import { getPackageInfo } from '../package-info.js';
+import { resolveWorkspaceRoot } from '../workspace/resolve.js';
+import { applyInitPlan, deriveInitChoices, detectedHostVersion, ensureDefaultRuntime, inspectInitContext, planWorkspaceInit, } from './init.js';
+const HOSTS = ['claude', 'codex', 'pi'];
+const HOST_COMMAND = {
+    claude: 'claude',
+    codex: 'codex',
+    pi: 'pi',
+};
+function sameMinor(left, right) {
+    const [leftMajor, leftMinor] = left.split('.');
+    const [rightMajor, rightMinor] = right.split('.');
+    return leftMajor === rightMajor && leftMinor === rightMinor;
+}
+function hostState(detected, pinned) {
+    if (detected === null)
+        return 'missing';
+    if (detected === pinned)
+        return 'verified';
+    return sameMinor(detected, pinned) ? 'unverified' : 'unsupported';
+}
+function detectHosts(pathEnv, requested) {
+    return HOSTS.filter((host) => requested === null || requested.includes(host)).map((host) => {
+        const pinnedVersion = HOST_SUPPORT[host].version;
+        const detectedVersion = detectedHostVersion(HOST_COMMAND[host], pathEnv);
+        return {
+            host,
+            command: HOST_COMMAND[host],
+            detectedVersion,
+            pinnedVersion,
+            state: hostState(detectedVersion, pinnedVersion),
+        };
+    });
+}
+export function parseHostList(value) {
+    if (value === null || value.trim() === '')
+        return null;
+    const parsed = [];
+    for (const entry of value.split(',')) {
+        const name = entry.trim();
+        if (name === 'claude' || name === 'codex' || name === 'pi') {
+            if (!parsed.includes(name))
+                parsed.push(name);
+            continue;
+        }
+        throw new Error(`Unknown host: ${name}`);
+    }
+    return parsed;
+}
+export async function planOnboard(options) {
+    const requestedRoot = resolve(options.root);
+    const resolution = await resolveWorkspaceRoot({ startPath: requestedRoot });
+    if (resolution.state === 'unavailable' || resolution.state === 'incomplete') {
+        return {
+            ok: false,
+            reason: 'unavailable',
+            message: `Cannot initialize from ${requestedRoot}.`,
+            diagnostics: resolution.diagnostics,
+        };
+    }
+    const root = resolution.root ?? requestedRoot;
+    const contextResult = await inspectInitContext(root);
+    if (!contextResult.ok) {
+        return {
+            ok: false,
+            reason: contextResult.status === 'invalid' ? 'invalid' : 'failed',
+            message: contextResult.message,
+            diagnostics: contextResult.diagnostics,
+        };
+    }
+    const context = contextResult.context;
+    const pathEnv = options.pathEnv ?? process.env['PATH'] ?? '';
+    const requestedHosts = options.hosts ?? null;
+    const derived = options.choices ??
+        (await deriveInitChoices(context.discovery, { pathEnv })).choices;
+    const choices = requestedHosts === null
+        ? derived
+        : { ...derived, hosts: [...requestedHosts] };
+    const prepared = await planWorkspaceInit({
+        root: context.root,
+        choices,
+        context,
+    });
+    if (!prepared.ok) {
+        return {
+            ok: false,
+            reason: prepared.status === 'invalid' ? 'invalid' : 'failed',
+            message: prepared.message,
+            diagnostics: prepared.diagnostics,
+        };
+    }
+    return {
+        context,
+        choices,
+        bundle: prepared.bundle,
+        hosts: detectHosts(pathEnv, requestedHosts),
+        requestedHosts: choices.hosts,
+    };
+}
+function hostTarget(host, root) {
+    if (host === 'claude')
+        return join(root, '.claude');
+    if (host === 'codex') {
+        const configured = process.env['CODEX_HOME'];
+        return configured === undefined || configured === ''
+            ? join(homedir(), '.codex')
+            : resolve(configured);
+    }
+    return null;
+}
+async function wireHost(plan, root, packageVersion) {
+    if (plan.state !== 'verified') {
+        const detail = plan.state === 'missing'
+            ? `Host ${plan.command} is not installed.`
+            : `Host ${plan.command} ${plan.detectedVersion ?? '(unknown)'} does not match the pinned ${plan.pinnedVersion}.`;
+        return {
+            ...plan,
+            action: 'skipped',
+            appliedFiles: [],
+            nextActions: [
+                `${detail} Install the pinned version, or use pappra host install --mode project-settings explicitly.`,
+            ],
+            diagnostics: [],
+        };
+    }
+    if (plan.host === 'pi') {
+        const outDir = join(root, '.pappra', 'host-bundles', 'pi');
+        try {
+            const exported = await exportHostPluginBundle({
+                host: 'pi',
+                hostVersion: plan.pinnedVersion,
+                outDir,
+                packageVersion,
+            });
+            return {
+                ...plan,
+                action: 'installed',
+                appliedFiles: exported.files.map((file) => `host-bundles/pi/${file}`),
+                nextActions: [
+                    `Run: pi install ${outDir} -l -a`,
+                    'Approve the project package trust prompt once in Pi.',
+                ],
+                diagnostics: [],
+            };
+        }
+        catch (error) {
+            return {
+                ...plan,
+                action: 'failed',
+                appliedFiles: [],
+                nextActions: [error instanceof Error ? error.message : String(error)],
+                diagnostics: [],
+            };
+        }
+    }
+    const target = hostTarget(plan.host, root);
+    if (target === null) {
+        return {
+            ...plan,
+            action: 'skipped',
+            appliedFiles: [],
+            nextActions: [`No install root is defined for ${plan.host}.`],
+            diagnostics: [],
+        };
+    }
+    await mkdir(target, { recursive: true });
+    const service = new HostIntegrationService({
+        root,
+        homeDir: homedir(),
+        pathEnv: process.env['PATH'] ?? '',
+        hostVersion: plan.pinnedVersion,
+        observedAt: new Date().toISOString(),
+    });
+    const installed = await service.install(plan.host, {
+        hostRoot: target,
+        hostVersion: plan.pinnedVersion,
+        apply: true,
+    });
+    const trust = plan.host === 'codex'
+        ? 'Approve the Pappra hook once in Codex; project `.codex/hooks.json` is not loaded by 0.163.0.'
+        : 'Reload the session and trust the Pappra hook if Claude Code prompts.';
+    return {
+        ...plan,
+        action: installed.status === 'applied'
+            ? 'installed'
+            : installed.status === 'unchanged'
+                ? 'unchanged'
+                : 'failed',
+        appliedFiles: installed.appliedFiles,
+        nextActions: [trust],
+        diagnostics: installed.diagnostics,
+    };
+}
+export async function applyOnboard(plan, options) {
+    const applied = await applyInitPlan(plan.bundle);
+    const diagnostics = [
+        ...plan.bundle.diagnostics,
+        ...applied.diagnostics,
+    ].filter((entry) => entry.severity !== 'info');
+    const runtime = applied.ok
+        ? await ensureDefaultRuntime(plan.bundle.scope.workspaceRoot, plan.bundle.scope.runtimeVersion)
+        : null;
+    if (runtime !== null) {
+        diagnostics.push(...runtime.diagnostics.filter((entry) => entry.severity !== 'info'));
+    }
+    const initComplete = applied.ok &&
+        applied.residualPaths.length === 0 &&
+        runtime?.completion === true;
+    const packageVersion = getPackageInfo().version;
+    const hosts = [];
+    const manualSteps = [];
+    for (const host of plan.hosts) {
+        const result = options.applyHosts
+            ? await wireHost(host, plan.bundle.scope.workspaceRoot, packageVersion)
+            : {
+                ...host,
+                action: 'planned',
+                appliedFiles: [],
+                nextActions: [
+                    'Rerun with --apply-host to write this host integration.',
+                ],
+                diagnostics: [],
+            };
+        hosts.push(result);
+        manualSteps.push(...result.nextActions);
+    }
+    const nextActions = [];
+    if (plan.choices.knowledge.sources.length > 0) {
+        nextActions.push('pappra docs scan --apply');
+    }
+    if (plan.choices.code.graph !== 'none' &&
+        plan.choices.repositories.length > 0) {
+        nextActions.push(`pappra code prepare --repo ${plan.choices.repositories[0]?.path ?? '<repo>'} --apply`);
+    }
+    return {
+        schema: 'pappra/onboard/1',
+        ok: initComplete && hosts.every((host) => host.action !== 'failed'),
+        dryRun: false,
+        workspaceRoot: plan.bundle.scope.workspaceRoot,
+        files: applied.appliedFiles.map((path) => ({ path, operation: 'write' })),
+        runtime: runtime?.runtime === null || runtime === null
+            ? null
+            : {
+                version: runtime.runtime.version,
+                status: runtime.runtime.status,
+            },
+        initComplete,
+        hosts,
+        manualSteps: [...new Set(manualSteps)],
+        nextActions,
+        diagnostics,
+    };
+}

package/dist/app/task-pin.d.ts

@@ -0,0 +1,23 @@
+export declare const TASK_PIN_SCHEMA = "pappra/task-pin/1";
+export interface TaskPin {
+    readonly schema: typeof TASK_PIN_SCHEMA;
+    readonly taskId: string;
+    readonly pinnedAt: string;
+}
+export interface TaskPinFailure {
+    readonly ok: false;
+    readonly message: string;
+}
+export declare function readTaskPin(root: string): Promise<TaskPin | null>;
+export declare function pinTask(root: string, taskId: string): Promise<TaskPin | TaskPinFailure>;
+export declare function unpinTask(root: string): Promise<{
+    ok: true;
+}>;
+/**
+ * Toggles the workspace-level auto-resume switch. The hook only injects a resume
+ * packet when this switch is on and a task pin exists; neither is inferred.
+ */
+export declare function setAutoResume(root: string, enabled: boolean): Promise<{
+    ok: true;
+} | TaskPinFailure>;
+export declare function readAutoResume(root: string): Promise<boolean>;

package/dist/app/task-pin.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { readTextFileBounded } from '../infra/fs.js';
+import { workspaceConfigSchema } from '../schemas/workspace.js';
+export const TASK_PIN_SCHEMA = 'pappra/task-pin/1';
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function pinPath(root) {
+    return join(root, '.pappra', 'local', 'current-task');
+}
+export async function readTaskPin(root) {
+    const read = await readTextFileBounded(pinPath(root), 64 * 1024);
+    if (!read.ok)
+        return null;
+    try {
+        const value = JSON.parse(read.value.text);
+        if (typeof value !== 'object' ||
+            value === null ||
+            !('schema' in value) ||
+            value.schema !== TASK_PIN_SCHEMA ||
+            !('taskId' in value) ||
+            typeof value.taskId !== 'string' ||
+            !TASK_ID.test(value.taskId)) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export async function pinTask(root, taskId) {
+    if (!TASK_ID.test(taskId)) {
+        return {
+            ok: false,
+            message: 'task id must be a short identifier (letters, digits, dot, dash, underscore).',
+        };
+    }
+    const pin = {
+        schema: TASK_PIN_SCHEMA,
+        taskId,
+        pinnedAt: new Date().toISOString(),
+    };
+    const target = pinPath(root);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(pin, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    await rename(temporary, target);
+    return pin;
+}
+export async function unpinTask(root) {
+    const target = pinPath(root);
+    const { rm } = await import('node:fs/promises');
+    await rm(target, { force: true });
+    return { ok: true };
+}
+/**
+ * Toggles the workspace-level auto-resume switch. The hook only injects a resume
+ * packet when this switch is on and a task pin exists; neither is inferred.
+ */
+export async function setAutoResume(root, enabled) {
+    const configPath = join(root, '.pappra', 'workspace.json');
+    const read = await readTextFileBounded(configPath, 1024 * 1024);
+    if (!read.ok) {
+        return { ok: false, message: read.message };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(read.value.text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `workspace.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const parsed = workspaceConfigSchema.safeParse({
+        ...(typeof raw === 'object' && raw !== null ? raw : {}),
+        continuity: { autoResume: enabled },
+    });
+    if (!parsed.success) {
+        return {
+            ok: false,
+            message: `workspace.json rejected the continuity switch: ${parsed.error.issues[0]?.message ?? 'invalid'}`,
+        };
+    }
+    const backup = join(root, '.pappra', 'local', 'backups', `task-pin-${randomUUID()}`, 'workspace.json');
+    await mkdir(dirname(backup), { recursive: true, mode: 0o700 });
+    await writeFile(backup, read.value.text, { mode: 0o600 });
+    const temporary = `${configPath}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(parsed.data, null, 2)}\n`);
+    await rename(temporary, configPath);
+    return { ok: true };
+}
+export async function readAutoResume(root) {
+    const read = await readFile(join(root, '.pappra', 'workspace.json'), 'utf8');
+    try {
+        const raw = JSON.parse(read);
+        if (typeof raw !== 'object' || raw === null || !('continuity' in raw)) {
+            return false;
+        }
+        const continuity = raw.continuity;
+        return (typeof continuity === 'object' &&
+            continuity !== null &&
+            'autoResume' in continuity &&
+            continuity.autoResume === true);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/commands/docs.js

@@ -1,5 +1,5 @@
-import { discoverWorkspace } from '../../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
+import { scanDiscoveredDocuments } from '../../knowledge/scan.js';
 import { formatDiagnostic } from '../../schemas/diagnostics.js';
 import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
@@ -10,96 +10,32 @@ export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\n' +
     '  scan   [--apply] [--json]\n\n' +
     'scan registers documents discovered under the configured knowledge sources; without\n' +
     '--apply it only reports the candidates.';
-function classifyScanKind(path) {
-    const lower = path.toLowerCase();
-    if (lower.endsWith('agents.md') || lower.endsWith('claude.md'))
-        return 'rule';
-    if (lower.includes('/research/'))
-        return 'research';
-    if (lower.includes('/adr/') || lower.includes('decision'))
-        return 'decision';
-    if (lower.includes('review') || lower.includes('retro'))
-        return 'review';
-    if (lower.includes('plan'))
-        return 'plan';
-    return 'architecture';
-}
 async function runDocsScan(options, output, root) {
-    const discovery = await discoverWorkspace(root);
-    const config = discovery.config;
-    if (config === null) {
-        return invalidArguments(output, options.json, 'docs scan requires a valid .pappra/workspace.json; run pappra init first.');
-    }
-    const service = new KnowledgeService(root);
-    const listed = await service.list({ includePrivate: true });
-    const registered = new Set(listed.records.flatMap((record) => record.location.kind === 'workspace' ? [record.location.path] : []));
-    const sources = config.knowledge.sources;
-    const visibility = config.knowledge.taskVisibility === 'shared' ? 'shareable' : 'private';
-    const candidates = (discovery.documents ?? []).flatMap((document) => {
-        const path = document.workspaceRelativePath;
-        if (path === null)
-            return [];
-        if (!sources.some((source) => path === source || path.startsWith(`${source}/`))) {
-            return [];
-        }
-        if (registered.has(path))
-            return [];
-        return [{ path, kind: classifyScanKind(path), visibility }];
-    });
+    const result = await scanDiscoveredDocuments(root, { apply: options.apply });
+    if ('message' in result) {
+        return invalidArguments(output, options.json, result.message);
+    }
     if (!options.apply) {
         if (options.json) {
-            output.stdout(`${JSON.stringify({
-                ok: true,
-                schema: 'pappra/docs-scan/1',
-                mode: 'plan',
-                workspaceRoot: root,
-                candidates,
-                registered: registered.size,
-                nextActions: [
-                    'Rerun with --apply to register these documents in the knowledge catalog.',
-                ],
-            })}\n`);
+            output.stdout(`${JSON.stringify(result)}\n`);
         }
         else {
-            output.stdout(`Scan candidates: ${candidates.length}\n`);
-            for (const candidate of candidates) {
+            output.stdout(`Scan candidates: ${result.candidates.length}\n`);
+            for (const candidate of result.candidates) {
                 output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
             }
             output.stdout('Plan only; rerun with --apply to register them.\n');
         }
         return 0;
     }
-    const registeredNow = [];
-    const diagnostics = [];
-    for (const candidate of candidates) {
-        const result = await service.register({
-            location: { kind: 'workspace', path: candidate.path },
-            kind: candidate.kind,
-            maturity: 'draft',
-            owner: 'human',
-            visibility: candidate.visibility,
-        });
-        diagnostics.push(...result.diagnostics);
-        if (result.ok)
-            registeredNow.push(result.record);
-    }
-    const ok = diagnostics.every((entry) => entry.severity !== 'error');
     if (options.json) {
-        output.stdout(`${JSON.stringify({
-            ok,
-            schema: 'pappra/docs-scan/1',
-            mode: 'apply',
-            workspaceRoot: root,
-            registered: registeredNow,
-            skipped: candidates.length - registeredNow.length,
-            diagnostics,
-        })}\n`);
+        output.stdout(`${JSON.stringify(result)}\n`);
     }
     else {
-        output.stdout(`Registered ${registeredNow.length} document(s).\n`);
-        printDiagnostics(output, diagnostics);
+        output.stdout(`Registered ${result.registered.length} document(s).\n`);
+        printDiagnostics(output, result.diagnostics);
     }
-    return ok ? 0 : 1;
+    return result.ok ? 0 : 1;
 }
 function printDiagnostics(output, diagnostics) {
     for (const diagnostic of diagnostics) {