@phyzess/pappra 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -46,6 +46,13 @@ npx @phyzess/pappra@beta runtime status --json
 npx @phyzess/pappra@beta runtime verify --json
 ```
 
+A workspace that already has a valid `.pappra/workspace.json` is never rewritten silently.
+`init --yes --reconfigure --apply` rebuilds it from discovery (for example to move the
+recorded runtime version to the running package), backing the previous file up under
+`.pappra/local/backups`. Apply also reports advisory `nextActions`: `pappra code prepare`
+for a selected code engine and `pappra docs scan --apply` to register documents from the
+configured knowledge sources.
+
 Optional examples have prerequisites rather than generated files: code-graph and
 host commands require the selected external CLI/support, and collaboration
 requires an explicit controller. They are not needed for the core workflow above.
@@ -56,7 +63,7 @@ requires an explicit controller. They are not needed for the core workflow above
 - **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
 - **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
 - **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
-- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle` exports a native plugin/package directory without registering it.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle` exports a native plugin/package directory without registering it. `host install --mode plugin` fails closed until plugin registration and callability are verified.
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -80,7 +87,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.3`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.3`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.4`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.4`, because pre-release versions are never republished.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/dist/app/init.d.ts

@@ -116,6 +116,8 @@ export interface PlanInitOptions {
     readonly root: string;
     readonly choices?: InitChoices | null;
     readonly runtimeVersion?: string;
+    /** Rebuilds workspace.json from selections even when a valid config exists. */
+    readonly reconfigure?: boolean;
     readonly planId?: string;
     readonly discoveredAt?: string;
     /** Reuse an immediately preceding inspectInitContext result. */

package/dist/app/init.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, join, resolve } from 'node:path';
-import { mkdir, open, readFile, rm, rmdir } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
 import { createDiagnostic, hasErrors, pointer, } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
 import { INIT_CHOICES_SCHEMA, initPlanSchema, parseInitChoices, } from '../schemas/init.js';
@@ -16,6 +16,7 @@ import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/conf
 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';
 const workspaceConfigRelativePath = '.pappra/workspace.json';
 const machineConfigRelativePath = '.pappra/local/machine.json';
@@ -666,22 +667,38 @@ function scopeRepositories(config, discovery) {
         };
     });
 }
-function planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig) {
+function planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig, existing) {
     const workspaceBytes = needWorkspaceConfig ? jsonBytes(config) : null;
     const machineBytes = needMachineConfig ? jsonBytes(machine) : null;
     const files = [];
-    if (workspaceBytes !== null) {
+    if (workspaceBytes !== null &&
+        existing.workspaceDigest !== sha256Digest(workspaceBytes)) {
         files.push({
             path: workspaceConfigRelativePath,
             bytes: workspaceBytes,
             beforeText: null,
+            ...(existing.workspaceDigest === null
+                ? {}
+                : {
+                    operation: 'replace-managed',
+                    expectedBeforeDigest: existing.workspaceDigest,
+                    backupRequired: true,
+                }),
         });
     }
-    if (machineBytes !== null) {
+    if (machineBytes !== null &&
+        existing.machineDigest !== sha256Digest(machineBytes)) {
         files.push({
             path: machineConfigRelativePath,
             bytes: machineBytes,
             beforeText: null,
+            ...(existing.machineDigest === null
+                ? {}
+                : {
+                    operation: 'replace-managed',
+                    expectedBeforeDigest: existing.machineDigest,
+                    backupRequired: true,
+                }),
         });
     }
     return { files, workspaceBytes, machineBytes };
@@ -787,14 +804,16 @@ export async function planWorkspaceInit(options) {
     const existingMachine = context.machineInspection.value;
     const diagnostics = [...context.diagnostics];
     const runtimeVersion = options.runtimeVersion ??
-        existingConfig?.runtimeVersion ??
+        (options.reconfigure === true
+            ? undefined
+            : existingConfig?.runtimeVersion) ??
         getPackageInfo().version;
     let config;
     let machine;
     let needWorkspaceConfig = false;
     let needMachineConfig = false;
     let selected = [];
-    if (existingConfig !== null) {
+    if (existingConfig !== null && options.reconfigure !== true) {
         config = existingConfig;
         if (choices !== null) {
             diagnostics.push(info(diagnosticCodes.initExistingConfigReused, 'Existing valid workspace configuration is reused; init selections do not overwrite it.', context.workspaceInspection.path, 'Use a future configure flow to change existing workspace policy.'));
@@ -816,7 +835,10 @@ export async function planWorkspaceInit(options) {
         if (choices === null) {
             return failure('needs_input', diagnosticCodes.initInputRequired, 'Workspace configuration is missing; init selections are required.', diagnostics, 'Provide --config with pappra/init-choices/1 selections, or run the interactive wizard.');
         }
-        const built = buildWorkspaceConfig(context.root, choices, context.discovery, runtimeVersion);
+        const effectiveChoices = existingConfig !== null && choices.workspaceId === undefined
+            ? { ...choices, workspaceId: existingConfig.workspaceId }
+            : choices;
+        const built = buildWorkspaceConfig(context.root, effectiveChoices, context.discovery, runtimeVersion);
         diagnostics.push(...built.diagnostics);
         if (built.config === null) {
             return failureFromDiagnostics('invalid', diagnostics, diagnosticCodes.initInvalidInput, 'Init selections do not form a valid workspace configuration.');
@@ -846,7 +868,10 @@ export async function planWorkspaceInit(options) {
             machine = parsedMachine.data;
         }
     }
-    const filePlan = planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig);
+    const filePlan = planFilesFor(config, machine, needWorkspaceConfig, needMachineConfig, {
+        workspaceDigest: context.workspaceInspection.digest,
+        machineDigest: context.machineInspection.digest,
+    });
     const configurationDigest = filePlan.workspaceBytes !== null
         ? sha256Digest(filePlan.workspaceBytes)
         : (context.workspaceInspection.digest ??
@@ -895,7 +920,9 @@ export async function planWorkspaceInit(options) {
         workspaceId: config.workspaceId,
         name: config.name,
         runtimeVersion: config.runtimeVersion,
-        configSource: existingConfig !== null ? 'existing' : 'planned',
+        configSource: existingConfig !== null && options.reconfigure !== true
+            ? 'existing'
+            : 'planned',
         repositories: scopeRepos,
         knowledge: config.knowledge,
         code: config.code,
@@ -1024,13 +1051,23 @@ async function verifyBundleWrites(bundle) {
                 hint: 'Regenerate the plan.',
             }));
         }
-        if (file.operation !== 'create') {
+        if (file.operation !== 'create' && file.operation !== 'replace-managed') {
             diagnostics.push(createDiagnostic({
                 code: diagnosticCodes.initApplyUnsupported,
                 severity: 'error',
-                message: `P03 apply supports only create operations; ${file.path} is ${file.operation}.`,
+                message: `Init apply does not support operation ${file.operation} for ${file.path}.`,
                 source: 'init plan',
-                hint: 'P04 will implement managed replacement with a journal and rollback.',
+                hint: 'Regenerate the plan with create or replace-managed operations.',
+            }));
+        }
+        if (file.operation === 'replace-managed' &&
+            file.expectedBeforeDigest === null) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.initPlanInvalid,
+                severity: 'error',
+                message: `Managed replacement for ${file.path} has no expected before digest.`,
+                source: 'init plan',
+                hint: 'Regenerate the plan; Pappra does not replace an unverified file.',
             }));
         }
         if (sha256Digest(write.bytes) !== file.nextDigest) {
@@ -1105,16 +1142,22 @@ export async function applyInitPlan(bundle, options = {}) {
     const workspaceInspection = await inspectWorkspaceConfig(root, {
         missing: 'info',
     });
-    const workspaceFilePlanned = bundle.plan.files.some((file) => file.path === workspaceConfigRelativePath);
-    if (workspaceFilePlanned) {
-        if (workspaceInspection.exists) {
+    const workspaceFileIndex = bundle.plan.files.findIndex((file) => file.path === workspaceConfigRelativePath);
+    const workspaceFile = workspaceFileIndex === -1 ? null : bundle.plan.files[workspaceFileIndex];
+    if (workspaceFile === null &&
+        (!workspaceInspection.exists ||
+            workspaceInspection.value === null ||
+            workspaceInspection.digest !== bundle.plan.configurationDigest)) {
+        return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+    }
+    if (workspaceFile !== null) {
+        if (workspaceFile.operation === 'create' && workspaceInspection.exists) {
             return applyFailure('conflict', diagnosticCodes.initTargetExists, 'Workspace configuration appeared after planning.', 'Remove or relocate the unexpected file, then retry init.');
         }
-    }
-    else if (!workspaceInspection.exists ||
-        workspaceInspection.value === null ||
-        workspaceInspection.digest !== bundle.plan.configurationDigest) {
-        return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+        if (workspaceFile.operation === 'replace-managed' &&
+            workspaceInspection.digest !== workspaceFile.expectedBeforeDigest) {
+            return planDiagnostics('Workspace configuration changed since planning.', diagnosticCodes.initPlanStale);
+        }
     }
     for (const file of bundle.plan.files) {
         const target = await safeTarget(root, file.path);
@@ -1122,29 +1165,28 @@ export async function applyInitPlan(bundle, options = {}) {
             return applyFailure('conflict', diagnosticCodes.initTargetUnsafe, `Planned target is not a safe workspace-relative path: ${file.path}`, 'Regenerate the plan; Pappra does not follow symlinked parents outside the workspace.');
         }
         const observation = await observePath(target.absolutePath);
-        if (observation.kind !== 'missing') {
-            return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned target already exists: ${file.path}`, 'Remove or relocate the unexpected file, then retry init.');
+        if (file.operation === 'create') {
+            if (observation.kind !== 'missing') {
+                return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned target already exists: ${file.path}`, 'Remove or relocate the unexpected file, then retry init.');
+            }
+            continue;
+        }
+        if (observation.kind !== 'file' || observation.stats === null) {
+            return applyFailure('conflict', diagnosticCodes.initTargetExists, `Planned replacement target is not a regular file: ${file.path}`, 'Inspect the target; Pappra does not replace directories or special files.');
+        }
+        const before = await readFile(target.absolutePath);
+        if (file.expectedBeforeDigest === null ||
+            sha256Digest(before) !== file.expectedBeforeDigest) {
+            return planDiagnostics(`Planned replacement target changed since planning: ${file.path}`, diagnosticCodes.initPlanStale);
         }
     }
-    const managedStart = await beginManagedApply(root, bundle.plan, bundle.writes, bundle.rootIdentity);
-    if (!managedStart.ok) {
-        const status = managedStart.status === 'invalid'
-            ? 'stale'
-            : managedStart.status === 'locked'
-                ? 'conflict'
-                : 'failed';
-        return {
-            ok: false,
-            status,
-            appliedFiles: [],
-            pendingExternalActions: [],
-            residualPaths: managedStart.residualPaths,
-            diagnostics: managedStart.diagnostics,
-        };
-    }
-    const managed = managedStart.context;
-    let created = [];
-    let createdDirectories = [];
+    const createIndexes = bundle.plan.files.flatMap((file, index) => file.operation === 'create' ? [index] : []);
+    const replaceIndexes = bundle.plan.files.flatMap((file, index) => file.operation === 'replace-managed' ? [index] : []);
+    let managed = null;
+    const created = [];
+    const createdDirectories = [];
+    const replacements = [];
+    let originalManifest = null;
     const ensureDirectory = async (directory) => {
         const missing = [];
         let current = directory;
@@ -1169,6 +1211,19 @@ export async function applyInitPlan(bundle, options = {}) {
             createdDirectories.push(path);
         }
     };
+    const restoreReplacements = async () => {
+        for (const replacement of [...replacements].reverse()) {
+            try {
+                await writeFile(replacement.absolutePath, replacement.beforeBytes);
+            }
+            catch {
+                // The residual list below and the failure diagnostic report this case.
+            }
+        }
+        if (originalManifest !== null) {
+            await writeWorkspaceManifest(root, originalManifest).catch(() => undefined);
+        }
+    };
     const rootBeforeWrite = await observePath(root);
     if (rootBeforeWrite.kind !== 'directory' ||
         rootBeforeWrite.stats === null ||
@@ -1177,73 +1232,169 @@ export async function applyInitPlan(bundle, options = {}) {
         return applyFailure('stale', diagnosticCodes.initPlanStale, 'Workspace root identity changed before writing.', 'Retry init from the current workspace root; no files were written.');
     }
     try {
-        for (const [index, file] of bundle.plan.files.entries()) {
+        for (const index of replaceIndexes) {
+            const file = bundle.plan.files[index];
             const write = bundle.writes[index];
-            if (write === undefined) {
-                throw new Error(`Missing planned bytes for ${file.path}.`);
+            await options.beforeWrite?.(file.path, index);
+            const absolutePath = resolvePortableRelativePath(root, file.path);
+            const backupRef = backupPath(root, bundle.plan.planId, file.path);
+            const stateBoundary = await ensureStatePathBoundary(root, backupRef);
+            if (!stateBoundary.ok)
+                throw new Error(stateBoundary.message);
+            const beforeBytes = await readFile(absolutePath);
+            if (file.expectedBeforeDigest === null ||
+                sha256Digest(beforeBytes) !== file.expectedBeforeDigest) {
+                throw new Error(`Replacement target changed again: ${file.path}`);
             }
-            const target = await safeTarget(root, file.path);
-            if (target === null) {
-                throw new Error(`Unsafe target: ${file.path}`);
+            const observation = await observePath(absolutePath);
+            const mode = observation.stats === null ? 0o644 : observation.stats.mode & 0o777;
+            await mkdir(dirname(backupRef), { recursive: true });
+            await writeFile(backupRef, beforeBytes, { mode: 0o600, flag: 'wx' });
+            const temporary = `${absolutePath}.pappra-replace-${randomUUID().slice(0, 8)}`;
+            await writeFile(temporary, write.bytes, { mode });
+            await rename(temporary, absolutePath);
+            const after = await observePath(absolutePath);
+            if (after.kind !== 'file' || after.stats === null) {
+                throw new Error(`Replacement target is unreadable after writing: ${file.path}`);
             }
-            await options.beforeWrite?.(file.path, index);
-            await ensureDirectory(dirname(target.absolutePath));
-            const handle = await open(target.absolutePath, 'wx');
-            const record = {
+            replacements.push({
                 path: file.path,
-                digest: file.nextDigest,
-                dev: -1,
-                ino: -1,
-            };
-            created.push(record);
-            try {
-                const stats = await handle.stat();
-                record.dev = stats.dev;
-                record.ino = stats.ino;
-                await handle.writeFile(write.bytes);
+                absolutePath,
+                beforeBytes,
+                backupRef,
+                backupDigest: sha256Digest(beforeBytes),
+                afterDigest: file.nextDigest,
+                identity: { dev: after.stats.dev, ino: after.stats.ino },
+            });
+        }
+        if (replacements.length > 0) {
+            const manifestRead = await readWorkspaceManifest(root);
+            if (manifestRead.diagnostics.length > 0) {
+                throw new Error(manifestRead.diagnostics[0]?.message ??
+                    'Workspace install manifest is unreadable.');
             }
-            finally {
-                await handle.close().catch(() => undefined);
+            if (manifestRead.value === null) {
+                throw new Error('Workspace install manifest is missing; Pappra does not adopt an unowned replacement.');
             }
-            const written = await readFile(target.absolutePath);
-            if (sha256Digest(written) !== file.nextDigest) {
-                throw new Error(`Written digest mismatch for ${file.path}.`);
+            originalManifest = manifestRead.value;
+            const entries = [...manifestRead.value.entries];
+            const verifiedAt = new Date().toISOString();
+            for (const replacement of replacements) {
+                const entry = {
+                    path: replacement.path,
+                    installId: bundle.plan.planId,
+                    operation: 'replace-managed',
+                    beforeDigest: replacement.backupDigest,
+                    afterDigest: replacement.afterDigest,
+                    backupRef: replacement.backupRef,
+                    backupDigest: replacement.backupDigest,
+                    identity: replacement.identity,
+                    owner: 'pappra',
+                    verifiedAt,
+                };
+                const existingIndex = entries.findIndex((item) => item.path === replacement.path);
+                if (existingIndex === -1)
+                    entries.push(entry);
+                else
+                    entries[existingIndex] = entry;
             }
-            const recorded = await recordManagedFile(managed, file.path, file.nextDigest, {
-                dev: record.dev,
-                ino: record.ino,
+            const written = await writeWorkspaceManifest(root, {
+                ...manifestRead.value,
+                entries,
             });
-            if (!recorded.ok) {
-                throw new Error(recorded.diagnostics[0]?.message ?? `Cannot record ${file.path}.`);
-            }
+            if (!written.ok)
+                throw new Error(written.message);
         }
-        const completed = await completeManagedApply(managed);
-        if (!completed.ok) {
-            const residual = await cleanupCreatedFiles(root, created);
-            const failed = await failManagedApply(managed, 'Cannot finalize managed installation manifest.', residual);
-            return {
-                ok: false,
-                status: 'failed',
-                appliedFiles: [],
-                pendingExternalActions: [],
-                residualPaths: failed.residualPaths,
-                diagnostics: failed.diagnostics,
+        if (createIndexes.length > 0) {
+            const createPlan = {
+                ...bundle.plan,
+                files: createIndexes.map((index) => bundle.plan.files[index]),
             };
+            const createWrites = createIndexes.map((index) => bundle.writes[index]);
+            const managedStart = await beginManagedApply(root, createPlan, createWrites, bundle.rootIdentity);
+            if (!managedStart.ok) {
+                const status = managedStart.status === 'invalid'
+                    ? 'stale'
+                    : managedStart.status === 'locked'
+                        ? 'conflict'
+                        : 'failed';
+                await restoreReplacements();
+                return {
+                    ok: false,
+                    status,
+                    appliedFiles: [],
+                    pendingExternalActions: [],
+                    residualPaths: managedStart.residualPaths,
+                    diagnostics: managedStart.diagnostics,
+                };
+            }
+            managed = managedStart.context;
+            for (const index of createIndexes) {
+                const file = bundle.plan.files[index];
+                const write = bundle.writes[index];
+                const target = await safeTarget(root, file.path);
+                if (target === null) {
+                    throw new Error(`Unsafe target: ${file.path}`);
+                }
+                await options.beforeWrite?.(file.path, index);
+                await ensureDirectory(dirname(target.absolutePath));
+                const handle = await open(target.absolutePath, 'wx');
+                const record = {
+                    path: file.path,
+                    digest: file.nextDigest,
+                    dev: 0,
+                    ino: 0,
+                };
+                try {
+                    await handle.writeFile(write.bytes);
+                    await handle.sync();
+                    const stats = await handle.stat();
+                    record.dev = stats.dev;
+                    record.ino = stats.ino;
+                }
+                finally {
+                    await handle.close();
+                }
+                created.push(record);
+                const recorded = await recordManagedFile(managed, file.path, file.nextDigest, { dev: record.dev, ino: record.ino });
+                if (!recorded.ok) {
+                    throw new Error(recorded.diagnostics[0]?.message ?? `Cannot record ${file.path}.`);
+                }
+            }
+            const completed = await completeManagedApply(managed);
+            if (!completed.ok) {
+                const residual = await cleanupCreatedFiles(root, created);
+                const failed = await failManagedApply(managed, 'Cannot finalize managed installation manifest.', residual);
+                await restoreReplacements();
+                return {
+                    ok: false,
+                    status: 'failed',
+                    appliedFiles: [],
+                    pendingExternalActions: [],
+                    residualPaths: failed.residualPaths,
+                    diagnostics: failed.diagnostics,
+                };
+            }
         }
+        const appliedFiles = [
+            ...created.map((file) => file.path),
+            ...replacements.map((replacement) => replacement.path),
+        ];
         return {
             ok: true,
             status: bundle.plan.externalActions.length > 0
                 ? 'external-actions-pending'
-                : created.length === 0
+                : appliedFiles.length === 0
                     ? 'no-changes'
                     : 'applied',
-            appliedFiles: created.map((file) => file.path),
+            appliedFiles,
             pendingExternalActions: bundle.plan.externalActions,
-            residualPaths: completed.residualPaths,
-            diagnostics: completed.diagnostics,
+            residualPaths: [],
+            diagnostics: [],
         };
     }
     catch (error) {
+        await restoreReplacements();
         const residual = await cleanupCreatedFiles(root, created);
         for (const directory of createdDirectories.reverse()) {
             await rmdir(directory).catch(() => undefined);
@@ -1259,6 +1410,25 @@ export async function applyInitPlan(bundle, options = {}) {
         const residualNote = residual.length === 0
             ? 'No planned file from this attempt remains.'
             : `Residual planned files require manual inspection: ${residual.join(', ')}`;
+        if (managed === null) {
+            return {
+                ok: false,
+                status,
+                appliedFiles: [],
+                pendingExternalActions: [],
+                residualPaths: residual,
+                diagnostics: [
+                    createDiagnostic({
+                        code,
+                        severity: 'error',
+                        message: `${base}. ${residualNote}`,
+                        source: 'init apply',
+                        pointer: null,
+                        hint: 'Inspect the workspace state; backups from this attempt were restored when possible.',
+                    }),
+                ],
+            };
+        }
         const failed = await failManagedApply(managed, `${base}. ${residualNote}`, residual);
         return {
             ok: false,

package/dist/cli/commands/docs.d.ts

@@ -7,5 +7,6 @@ export interface DocsCommandOptions {
     readonly json: boolean;
     readonly includePrivate: boolean;
     readonly includeArchived: boolean;
+    readonly apply: boolean;
 }
 export declare function runDocsCommand(options: DocsCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/docs.js

@@ -1,11 +1,106 @@
+import { discoverWorkspace } from '../../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
 import { formatDiagnostic } from '../../schemas/diagnostics.js';
 import { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
-export const docsUsage = 'pappra docs <list|check|archive> [options]\n' +
+export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\n' +
     '  list   [--include-private] [--include-archived] [--json]\n' +
     '  check  [--include-private] [--json]\n' +
-    '  archive <documentId> [--json]';
+    '  archive <documentId> [--json]\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 }];
+    });
+    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`);
+        }
+        else {
+            output.stdout(`Scan candidates: ${candidates.length}\n`);
+            for (const candidate of 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`);
+    }
+    else {
+        output.stdout(`Registered ${registeredNow.length} document(s).\n`);
+        printDiagnostics(output, diagnostics);
+    }
+    return ok ? 0 : 1;
+}
 function printDiagnostics(output, diagnostics) {
     for (const diagnostic of diagnostics) {
         output.stderr(`${formatDiagnostic(diagnostic)}\n`);
@@ -55,7 +150,7 @@ export async function runDocsCommand(options, output) {
     }
     const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
     const serviceRoot = resolution.root ?? options.cwd;
-    if (!['list', 'check', 'archive'].includes(options.action)) {
+    if (!['list', 'check', 'archive', 'scan'].includes(options.action)) {
         return invalidArguments(output, options.json, `unknown docs action: ${options.action}`);
     }
     if (options.action === 'archive' && options.argument === null) {
@@ -64,6 +159,12 @@ export async function runDocsCommand(options, output) {
     if (options.action !== 'archive' && options.argument !== null) {
         return invalidArguments(output, options.json, `docs ${options.action} does not accept an argument`);
     }
+    if (options.action === 'scan') {
+        return runDocsScan(options, output, serviceRoot);
+    }
+    if (options.apply) {
+        return invalidArguments(output, options.json, 'only docs scan accepts --apply');
+    }
     if (options.action === 'archive' && options.argument !== null) {
         const service = new KnowledgeService(serviceRoot);
         const result = await service.archive(options.argument);

package/dist/cli/commands/host.d.ts

@@ -10,5 +10,6 @@ export interface HostCommandOptions {
     readonly hostVersion: string | null;
     readonly apply: boolean;
     readonly out: string | null;
+    readonly mode: 'project-settings' | 'plugin' | null;
 }
 export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -5,7 +5,8 @@ import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.js
 import { HOST_SUPPORT, isSupportedVersion, } from '../../hosts/integration/support.js';
 import { getPackageInfo } from '../../package-info.js';
 export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundle> --host <pi|codex|claude>\n' +
-    '  [--host-root <dir>] [--host-version <version>] [--out <dir>] [--apply] [--json]\n' +
+    '  [--host-root <dir>] [--host-version <version>] [--out <dir>]\n' +
+    '  [--mode project-settings|plugin] [--apply] [--json]\n' +
     '\n' +
     'bundle exports a host-native plugin/package directory and never registers it or\n' +
     'claims host callability.';
@@ -102,6 +103,7 @@ export async function runHostCommand(options, output) {
         const result = await service.install(options.host, {
             ...target,
             apply: options.apply,
+            ...(options.mode === null ? {} : { mode: options.mode }),
         });
         if (options.json) {
             output.stdout(`${JSON.stringify(result)}\n`);

package/dist/cli/commands/init.d.ts

@@ -38,6 +38,8 @@ export interface InitCommandOptions {
     readonly printChoices?: boolean;
     /** Leaves the runtime action pending instead of installing a durable copy. */
     readonly noRuntime?: boolean;
+    /** Rebuilds workspace.json from the selections even when a valid config exists. */
+    readonly reconfigure?: boolean;
 }
 export interface RuntimeFlowResult {
     readonly ok: boolean;

package/dist/cli/commands/init.js

@@ -586,12 +586,26 @@ function printApply(output, result, runtimeRequested) {
             : 'Only planned config files were applied. Initialization is not complete until runtime/provider actions are authorized and executed.\n');
     }
 }
+function advisoryNextActions(bundle) {
+    const actions = [];
+    const repositoryId = bundle.scope.repositories[0]?.id;
+    if (bundle.scope.code.graph !== 'none' &&
+        bundle.scope.repositories.length > 0 &&
+        repositoryId !== undefined) {
+        actions.push(`pappra code prepare --repo ${repositoryId} --apply   # register the ${bundle.scope.code.graph} index for this checkout`);
+    }
+    if (bundle.scope.knowledge.sources.length > 0) {
+        actions.push('pappra docs scan --apply   # register discovered knowledge documents in the catalog');
+    }
+    return actions;
+}
 function planJson(bundle) {
     return {
         command: 'init',
         mode: 'plan',
         plan: bundle.plan,
         scope: bundle.scope,
+        nextActions: advisoryNextActions(bundle),
         diagnostics: bundle.diagnostics,
     };
 }
@@ -716,6 +730,7 @@ export async function runInitCommand(options, output, deps = {}) {
         root: context.root,
         choices,
         context,
+        ...(options.reconfigure === true ? { reconfigure: true } : {}),
     });
     if (!prepared.ok)
         return writeFailure(output, options, prepared);
@@ -748,6 +763,7 @@ export async function runInitCommand(options, output, deps = {}) {
             apply: applied,
             runtime: runtimeFlow?.runtime ?? null,
             initComplete,
+            nextActions: advisoryNextActions(bundle),
             diagnostics: [
                 ...bundle.diagnostics,
                 ...(runtimeFlow?.diagnostics ?? []),
@@ -814,6 +830,9 @@ export async function runInitCommand(options, output, deps = {}) {
             return 1;
         }
         output.stdout('Durable runtime copy installed and bound. Initialization complete.\n');
+        for (const action of advisoryNextActions(bundle)) {
+            output.stdout(`  next: ${action}\n`);
+        }
         return 0;
     }
     return applied.status === 'external-actions-pending' ? 1 : 0;

package/dist/cli/run.js

@@ -20,9 +20,11 @@ function parseOptions(args) {
             apply: { type: 'boolean' },
             yes: { type: 'boolean', short: 'y' },
             'no-runtime': { type: 'boolean' },
+            reconfigure: { type: 'boolean' },
             from: { type: 'string' },
             tarball: { type: 'string' },
             out: { type: 'string' },
+            mode: { type: 'string' },
             bind: { type: 'boolean' },
             force: { type: 'boolean' },
             'no-interactive': { type: 'boolean' },
@@ -182,7 +184,11 @@ function parseOptions(args) {
     };
 }
 function failure(output, json, code, error) {
-    const message = error instanceof Error ? error.message : 'Operation failed.';
+    const message = typeof error === 'string'
+        ? error
+        : error instanceof Error
+            ? error.message
+            : 'Operation failed.';
     if (json) {
         output.stdout(`${JSON.stringify({ ok: false, code, message })}\n`);
     }
@@ -230,18 +236,32 @@ export async function runCli(args, output) {
     }
     const { values, command, docsAction, docsArgument, codeAction, hostAction, collaborationAction, resumeTaskId, runtimeAction, } = parsed;
     const json = values.json === true;
+    const applyRequested = values.apply === true;
     if (command !== 'init' &&
         (values.yes === true ||
             values['no-interactive'] === true ||
             values['print-choices'] === true ||
-            values['no-runtime'] === true)) {
-        failure(output, json, 'invalid_arguments', '--yes, --no-interactive, --print-choices and --no-runtime are only valid for init.');
+            values['no-runtime'] === true ||
+            values.reconfigure === true)) {
+        failure(output, json, 'invalid_arguments', '--yes, --no-interactive, --print-choices, --no-runtime and --reconfigure are only valid for init.');
         return 2;
     }
     if (command !== 'host' && values.out !== undefined) {
         failure(output, json, 'invalid_arguments', '--out is only valid for host.');
         return 2;
     }
+    if (command !== 'host' &&
+        values.mode !== undefined &&
+        command !== 'runtime') {
+        failure(output, json, 'invalid_arguments', '--mode is only valid for host.');
+        return 2;
+    }
+    if (values.mode !== undefined &&
+        values.mode !== 'project-settings' &&
+        values.mode !== 'plugin') {
+        failure(output, json, 'invalid_arguments', '--mode accepts project-settings or plugin.');
+        return 2;
+    }
     if (command !== 'runtime' &&
         (values.from !== undefined ||
             values.tarball !== undefined ||
@@ -284,7 +304,6 @@ export async function runCli(args, output) {
         if (action === null ||
             values.version ||
             values.config !== undefined ||
-            values.apply === true ||
             values['install-runtime'] === true ||
             values['runtime-tarball'] !== undefined ||
             values['runtime-version'] !== undefined ||
@@ -309,13 +328,12 @@ export async function runCli(args, output) {
     if (command === 'docs') {
         if (values.version ||
             values.config !== undefined ||
-            values.apply === true ||
             values['install-runtime'] === true ||
             values['runtime-tarball'] !== undefined ||
             values['runtime-version'] !== undefined ||
             values.root !== undefined ||
             hasContinuityOptions(values)) {
-            failure(output, json, 'invalid_arguments', 'docs only accepts list/check/archive, --include-private, --include-archived, --help, and --json.');
+            failure(output, json, 'invalid_arguments', 'docs only accepts list/check/archive/scan, --include-private, --include-archived, --apply (scan only), --help, and --json.');
             return 2;
         }
         if (values.help) {
@@ -334,6 +352,7 @@ export async function runCli(args, output) {
             json,
             includePrivate: values['include-private'] === true,
             includeArchived: values['include-archived'] === true,
+            apply: applyRequested,
         }, output);
     }
     if (command === 'doctor') {
@@ -395,6 +414,7 @@ export async function runCli(args, output) {
             yes: values.yes === true || values['no-interactive'] === true,
             printChoices: values['print-choices'] === true,
             noRuntime: values['no-runtime'] === true,
+            reconfigure: values.reconfigure === true,
         }, output);
     }
     if (command === 'runtime') {
@@ -638,6 +658,7 @@ export async function runCli(args, output) {
             values.rebuild === true ||
             hasContinuityOptions(values) ||
             (values.apply === true && action !== 'install') ||
+            (values.mode !== undefined && action !== 'install') ||
             (values['host-root'] !== undefined && action === null) ||
             (values['host-version'] !== undefined && action === null);
         if (values.help) {
@@ -662,6 +683,9 @@ export async function runCli(args, output) {
             hostVersion: values['host-version'] ?? null,
             apply: values.apply === true,
             out: values.out ?? null,
+            mode: values.mode === 'project-settings' || values.mode === 'plugin'
+                ? values.mode
+                : null,
         }, output);
     }
     if (command !== null) {

package/dist/hosts/integration/service.d.ts

@@ -14,6 +14,12 @@ export interface HostTargetOptions {
     readonly hostVersion?: string | null;
     /** Rewrites a manifest previously pinned to a package checkout path. */
     readonly migrate?: boolean;
+    /**
+     * Plugin wiring is exported with `host bundle` but not installed here: host
+     * registration, trust and callability are unverified, so this mode fails
+     * closed instead of writing a bundle a host may never load.
+     */
+    readonly mode?: 'project-settings' | 'plugin';
 }
 export interface HostPlanBundle {
     readonly plan: HostIntegrationPlan;

package/dist/hosts/integration/service.js

@@ -884,6 +884,19 @@ export class HostIntegrationService {
         return planFromFiles(host, this.#root, hostRoot, target.expression, built.bundle.bundleDigest, built.files);
     }
     async install(host, options) {
+        if (options.mode === 'plugin') {
+            return hostIntegrationResultSchema.parse({
+                schema: 'pappra/host-integration/1',
+                ok: false,
+                status: 'unsupported',
+                plan: null,
+                appliedFiles: [],
+                residualPaths: [],
+                diagnostics: [
+                    diagnostic(diagnosticCodes.host_unavailable, 'Plugin install mode is not wired: host registration, trust and callability are unverified.', this.#root, 'Use `pappra host bundle --host <name> --out <dir>` to export the plugin directory and register it yourself; project-settings install remains the verified mode.'),
+                ],
+            });
+        }
         let plan;
         let contents;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"