@phyzess/pappra 0.1.0-beta.14 → 0.1.0-beta.19

package/dist/cli/commands/collaboration-transition.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import { applySessionTransition, loadSessionTransitionRequest, planSessionTransition, } from '../../app/collab-session-transition.js';
+export const collaborationTransitionUsage = 'pappra collab transition <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n\n' +
+    'Plan is read-only. Apply resumes one guarded durable transition stage at a time.\n' +
+    'Pi idle/settled events, a managed freeze latch and transcript data are not native\n' +
+    'quiescence proof. Unsupported host proof blocks before successor launch or claim\n' +
+    'transfer. ACK and first-work messages must be registered and applied; task retirement\n' +
+    'writes a reversible marker only and never archives the native Pi session.';
+function emitHuman(report, output) {
+    output.stdout(`Session transition ${report.action}: ${report.status}${report.code === null ? '' : ` (${report.code})`}.\n`);
+    if (report.message !== null)
+        output.stdout(`  ${report.message}\n`);
+    output.stdout(`  task: ${report.task_id ?? '<unavailable>'} (${report.task_root})\n`);
+    output.stdout(`  transition: ${report.transition_id || '<unavailable>'}; stage: ${report.stage}\n`);
+    if (report.next_action !== null)
+        output.stdout(`  next: ${report.next_action}\n`);
+    if (report.steps.length > 0) {
+        output.stdout('  stages:\n');
+        for (const item of report.steps)
+            output.stdout(`    ${item.step}: ${item.status}${item.code === null ? '' : ` (${item.code})`}${item.detail === null ? '' : ` — ${item.detail}`}\n`);
+    }
+    if (report.route_transfer !== null)
+        output.stdout(`  route/claims: ${JSON.stringify(report.route_transfer)}\n`);
+    if (report.first_work !== null)
+        output.stdout(`  first work: ${JSON.stringify(report.first_work)}\n`);
+    if (report.archive !== null)
+        output.stdout(`  retirement: ${JSON.stringify(report.archive)}\n`);
+    output.stdout(`  capabilities: quiescence ${report.capabilities.supported_quiescence}, native archive ${report.capabilities.native_session_archive}, route exclusion ${report.capabilities.notification_route_exclusion}\n`);
+    if (report.limits.length > 0)
+        output.stdout(`  limits: ${report.limits.join('; ')}\n`);
+}
+function invalid(options, output, code, message) {
+    if (options.json)
+        output.stdout(`${JSON.stringify({ ok: false, status: 'invalid', code, message })}\n`);
+    else {
+        output.stderr(`pappra: ${message}\n`);
+        output.stderr(`${collaborationTransitionUsage}\n`);
+    }
+    return 2;
+}
+export async function runCollaborationTransitionCommand(options, output, dependencies = {}) {
+    if (options.action === null)
+        return invalid(options, output, 'transition_action_required', 'collab transition requires plan or apply.');
+    if (options.taskRoot === null || options.requestFile === null)
+        return invalid(options, output, 'required_option_missing', 'collab transition requires --task-root and --request.');
+    if (!path.isAbsolute(options.taskRoot) ||
+        !path.isAbsolute(options.requestFile))
+        return invalid(options, output, 'absolute_path_required', '--task-root and --request must be absolute paths.');
+    const loaded = loadSessionTransitionRequest(options.requestFile);
+    if (!loaded.ok) {
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, status: loaded.kind, code: loaded.code, message: loaded.message, next_action: loaded.next_action })}\n`);
+        else {
+            output.stderr(`${loaded.code}: ${loaded.message}\n`);
+            if (loaded.next_action !== null)
+                output.stderr(`${loaded.next_action}\n`);
+        }
+        return 2;
+    }
+    if (path.resolve(loaded.value.request.task_root) !==
+        path.resolve(options.taskRoot))
+        return invalid(options, output, 'task_root_mismatch', 'The request task_root does not equal --task-root.');
+    const report = options.action === 'plan'
+        ? await planSessionTransition(loaded.value, dependencies)
+        : await applySessionTransition(loaded.value, dependencies);
+    if (options.json)
+        output.stdout(`${JSON.stringify(report)}\n`);
+    else
+        emitHuman(report, output);
+    if (report.status === 'invalid')
+        return 2;
+    if (report.action === 'apply' && report.status === 'waiting')
+        return 1;
+    return report.ok ? 0 : 1;
+}

package/dist/cli/commands/collaboration-work-run.d.ts

@@ -0,0 +1,34 @@
+import { type WorkExecutionAdapter } from '../../app/collab-work-execution.js';
+import type { CliOutput } from '../output.js';
+export declare const collaborationWorkRunUsage: string;
+export interface CollaborationWorkRunOptions {
+    readonly requestFile: string | null;
+    readonly apply: boolean;
+    readonly json: boolean;
+}
+export interface CollaborationWorkRunParse {
+    readonly options: CollaborationWorkRunOptions;
+    readonly errors: readonly string[];
+}
+export interface WorkExecutionRequestFile {
+    readonly schema: 'pappra/collab-work-execution-request/1';
+    readonly task_root: string;
+    readonly plan_file: string;
+    readonly binding_file: string;
+    readonly caller: {
+        readonly agent_id: string;
+        readonly session_id: string;
+        readonly harness: string;
+        readonly cwd: string;
+    };
+    readonly caller_pane: string;
+    readonly capability_cards: readonly {
+        readonly assignment_id: string;
+        readonly capabilities_file: string;
+    }[];
+    readonly max_concurrency?: number;
+}
+export declare function parseCollaborationWorkRunArgs(argv: readonly string[]): CollaborationWorkRunParse;
+export declare function runCollaborationWorkRunCommand(options: CollaborationWorkRunOptions, output: CliOutput, deps?: {
+    readonly adapter?: WorkExecutionAdapter;
+}): Promise<number>;

package/dist/cli/commands/collaboration-work-run.js

@@ -0,0 +1,178 @@
+import path from 'node:path';
+import { readBoundedFile } from '../../app/bounded-file.js';
+import { COLLAB_WORK_EXECUTION_SCHEMA, runWorkExecution, } from '../../app/collab-work-execution.js';
+const MAX_REQUEST_BYTES = 64 * 1024;
+export const collaborationWorkRunUsage = 'pappra collab work-run --request <abs work-execution.json> [--apply] [--json]\n\n' +
+    'Without --apply this is a zero-write, zero-notification plan. Apply revalidates the\n' +
+    'pinned work plan, current assignments, capability cards, coordinator epoch, resource\n' +
+    'claims and visible participant binding; it records a durable per-node intent before\n' +
+    'one bounded concurrent notification batch. Existing/unknown intents are reconciliation\n' +
+    'only and are never automatically replayed. This command never launches sessions, merges\n' +
+    'code or accepts a report.';
+export function parseCollaborationWorkRunArgs(argv) {
+    const errors = [];
+    let requestFile = null;
+    let apply = false;
+    let json = false;
+    let sawApply = false;
+    let sawJson = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--request') {
+            if (requestFile !== null)
+                errors.push('--request may be given only once.');
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                errors.push('--request requires a value.');
+            else {
+                requestFile = value;
+                index += 1;
+            }
+        }
+        else if (arg === '--apply') {
+            if (sawApply)
+                errors.push('--apply may be given only once.');
+            sawApply = true;
+            apply = true;
+        }
+        else if (arg === '--json') {
+            if (sawJson)
+                errors.push('--json may be given only once.');
+            sawJson = true;
+            json = true;
+        }
+        else
+            errors.push(`unknown option: ${String(arg)}`);
+    }
+    return { options: { requestFile, apply, json }, errors };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isAbsolute(value) {
+    return typeof value === 'string' && path.isAbsolute(value);
+}
+function loadRequest(file) {
+    const read = readBoundedFile(file, MAX_REQUEST_BYTES);
+    if (!read.ok)
+        return { ok: false, error: `request_file_${read.code}` };
+    let parsed;
+    try {
+        parsed = JSON.parse(read.text);
+    }
+    catch {
+        return { ok: false, error: 'request_file_invalid_json' };
+    }
+    if (!isObject(parsed) ||
+        parsed.schema !== 'pappra/collab-work-execution-request/1')
+        return { ok: false, error: 'request_schema_invalid' };
+    const keys = Object.keys(parsed).sort();
+    const expected = [
+        'binding_file',
+        'caller',
+        'caller_pane',
+        'capability_cards',
+        'plan_file',
+        'schema',
+        'task_root',
+    ];
+    const expectedOptional = [...expected, 'max_concurrency'].sort();
+    if (keys.join('|') !== expected.sort().join('|') &&
+        keys.join('|') !== expectedOptional.join('|'))
+        return { ok: false, error: 'request_fields_invalid' };
+    if (!isAbsolute(parsed.task_root) ||
+        !isAbsolute(parsed.plan_file) ||
+        !isAbsolute(parsed.binding_file))
+        return { ok: false, error: 'request_paths_must_be_absolute' };
+    if (typeof parsed.caller_pane !== 'string' ||
+        !/^[A-Za-z0-9]+:p[A-Za-z0-9]+$/.test(parsed.caller_pane))
+        return { ok: false, error: 'caller_pane_invalid' };
+    if (!isObject(parsed.caller) ||
+        Object.keys(parsed.caller).sort().join('|') !==
+            'agent_id|cwd|harness|session_id' ||
+        typeof parsed.caller.agent_id !== 'string' ||
+        typeof parsed.caller.session_id !== 'string' ||
+        typeof parsed.caller.harness !== 'string' ||
+        !isAbsolute(parsed.caller.cwd))
+        return { ok: false, error: 'caller_identity_invalid' };
+    if (!Array.isArray(parsed.capability_cards) ||
+        parsed.capability_cards.length > 64)
+        return { ok: false, error: 'capability_cards_invalid' };
+    const assignmentIds = new Set();
+    const cards = [];
+    for (const item of parsed.capability_cards) {
+        if (!isObject(item) ||
+            Object.keys(item).sort().join('|') !==
+                'assignment_id|capabilities_file' ||
+            typeof item.assignment_id !== 'string' ||
+            !isAbsolute(item.capabilities_file) ||
+            assignmentIds.has(item.assignment_id))
+            return { ok: false, error: 'capability_cards_invalid' };
+        assignmentIds.add(item.assignment_id);
+        cards.push({
+            assignment_id: item.assignment_id,
+            capabilities_file: item.capabilities_file,
+        });
+    }
+    const maxConcurrency = parsed.max_concurrency;
+    if (maxConcurrency !== undefined &&
+        (typeof maxConcurrency !== 'number' ||
+            !Number.isSafeInteger(maxConcurrency) ||
+            maxConcurrency < 1 ||
+            maxConcurrency > 8))
+        return { ok: false, error: 'max_concurrency_invalid' };
+    return {
+        ok: true,
+        value: {
+            task_root: parsed.task_root,
+            plan_file: parsed.plan_file,
+            binding_file: parsed.binding_file,
+            caller: parsed.caller,
+            caller_pane: parsed.caller_pane,
+            capability_cards: cards,
+            ...(maxConcurrency === undefined
+                ? {}
+                : { max_concurrency: maxConcurrency }),
+        },
+    };
+}
+function invalid(output, options, errors) {
+    if (options.json)
+        output.stdout(`${JSON.stringify({ schema: COLLAB_WORK_EXECUTION_SCHEMA, ok: false, status: 'invalid', errors })}\n`);
+    else {
+        output.stdout('Work execution request invalid.\n');
+        for (const error of errors)
+            output.stdout(`  - ${error}\n`);
+        output.stdout(`\n${collaborationWorkRunUsage}\n`);
+    }
+    return 2;
+}
+function emitHuman(report, output) {
+    output.stdout(`Work execution ${report.apply ? 'apply' : 'plan'}: ${report.status}${report.task_id ? ` (${report.task_id})` : ''}.\n`);
+    output.stdout(`  nodes ${report.nodes.length}, concurrent limit ${report.concurrency.limit}, actual overlap ${report.concurrency.actual_overlap ? 'yes' : 'no'}\n`);
+    for (const node of report.nodes) {
+        output.stdout(`  ${node.role} ${node.node_id} (${node.assignment_id}#${node.attempt}): ${node.execution_status}; acceptance ${node.acceptance}\n`);
+        for (const blocker of node.blockers)
+            output.stdout(`    - ${blocker}\n`);
+        if (node.intent_message_id)
+            output.stdout(`    intent: ${node.intent_message_id}\n`);
+    }
+    output.stdout(`  immutable report pointers: ${report.reports.length}; no merge or acceptance performed\n`);
+}
+export async function runCollaborationWorkRunCommand(options, output, deps = {}) {
+    if (options.requestFile === null)
+        return invalid(output, options, ['--request is required.']);
+    if (!path.isAbsolute(options.requestFile))
+        return invalid(output, options, ['--request must be absolute.']);
+    const request = loadRequest(options.requestFile);
+    if (!request.ok)
+        return invalid(output, options, [request.error]);
+    const report = await runWorkExecution({ request: request.value, apply: options.apply }, deps);
+    if (options.json)
+        output.stdout(`${JSON.stringify(report)}\n`);
+    else
+        emitHuman(report, output);
+    if (report.status === 'planned' || report.status === 'applied')
+        return 0;
+    return report.status === 'invalid' ? 2 : 1;
+}

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

@@ -1,4 +1,6 @@
 import type { CliOutput } from '../output.js';
+/** One source of truth for the full collaboration command family in help output. */
+export declare const collaborationCommandLine = "pappra collab <prepare|run|work-run|role-run|query|preflight|plan|role-plan|bootstrap|rollover|transition|message|capabilities|state|resource|handoff|recovery|recovery-run|binding> [options]";
 export declare const collaborationUsage: string;
 export interface CollaborationCommandOptions {
     readonly cwd: string;
@@ -9,5 +11,7 @@ export interface CollaborationCommandOptions {
     readonly capabilitiesFile: string | null;
     readonly controller: string | null;
     readonly domainRoot: string | null;
+    readonly rpcRequestTimeoutMs?: number;
+    readonly rpcOperationTimeoutMs?: number;
 }
 export declare function runCollaborationCommand(options: CollaborationCommandOptions, output: CliOutput, input?: NodeJS.ReadableStream): Promise<number>;

package/dist/cli/commands/collaboration.js

@@ -1,10 +1,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { FixtureController, PiRpcController, driveRun, inspectPreparedHistory, prepareCollaboration, startPrepared, } from '../../app/collaboration.js';
-export const collaborationUsage = 'pappra collab <prepare|run|query> [options]\n' +
+/** One source of truth for the full collaboration command family in help output. */
+export const collaborationCommandLine = 'pappra collab <prepare|run|work-run|role-run|query|preflight|plan|role-plan|bootstrap|rollover|transition|message|capabilities|state|resource|handoff|recovery|recovery-run|binding> [options]';
+export const collaborationUsage = `${collaborationCommandLine}\n` +
     '  prepare --goal <file> --domain-root <dir> [--json]\n' +
     '  run --prepared <file> --capabilities <card> --controller <fixture|pi-rpc>\n' +
+    '    [--rpc-request-timeout-ms <1..60000>] [--rpc-operation-timeout-ms <1..86400000>]\n' +
+    '  work-run --request <abs work-execution.json> [--apply] [--json]\n' +
+    '  role-run --request <abs role-orchestration.json> [--apply] [--json]\n' +
+    '    Apply records bounded notification intents; plans write and notify nothing.\n' +
     '  query --prepared <file> [--json]\n' +
+    '  preflight --assignment <file> --capabilities <card> [--max-age-minutes <n>] [--json]\n' +
+    '  plan --task-root <dir> --config <plan.json> [--json]\n' +
+    '  role-plan expand --request <abs role-plan.json> [--json]\n' +
+    '  role-plan aggregate --request <abs role-plan.json> --task-root <abs> --config <abs expanded-plan.json> [--json]\n' +
+    '  rollover <inspect|plan> --task-root <dir> --request <request.json> [--json]\n' +
+    '  bootstrap <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n' +
+    '    Plan is read-only; apply launches only a visible Pi sibling or verified task-bound reuse.\n' +
+    '    Unknown effects are reconciled, not retried; submission is not acceptance.\n' +
+    '    Rollover remains read-only: no apply, native stop proof, route removal or session archive.\n' +
+    '  transition <plan|apply> --task-root <abs> --request <abs request.json> [--json]\n' +
+    '    Pre-transfer apply requires the opt-in Pi host; first-work and retirement resume from CLI.\n' +
+    '    Unsupported native-quiescence proof blocks before successor launch or claim transfer.\n' +
+    '    Applied ACK and REPORT pointers are required; retirement retains the original transcript.\n' +
+    '  message <send|list|read|notify> --task-root <dir> [options]\n' +
+    '  capabilities derive --harness <pi|codex|claude> --assignment <file> --template <file> [--execution <file> | --live] [--session <file> | --events <file>] [--json]\n' +
+    '  state <show|doctor|epoch-check> --task-root <dir> [options]\n' +
+    '  resource <list|claim|release> --task-root <dir> [options]\n' +
+    '  handoff <inventory|begin|stopped|rebind|transfer|confirm|complete|abort|release-dispatch> --task-root <dir> [options]\n' +
+    '  recovery <inspect|reconcile|lock-break> --task-root <dir> [options]\n' +
+    '  recovery-run --request <abs recovery-run.json> [--apply] [--json]\n' +
+    '    Apply requires exact session/cwd/harness/pane and a task-local digest-pinned binding.\n' +
+    '  binding <list|resolve|bind|unbind> [--root <dir>] [options]\n' +
     '  run reads pappra/collaboration-command/1 JSONL from stdin and writes\n' +
     '  pappra/collaboration-event/1 JSONL to stdout.';
 function failure(code, message) {
@@ -17,11 +45,18 @@ function readGoal(file) {
     }
     return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
-function controllerFor(name) {
+function controllerFor(name, options) {
     if (name === 'fixture')
         return new FixtureController();
     if (name === 'pi-rpc')
-        return new PiRpcController();
+        return new PiRpcController({
+            ...(options.rpcRequestTimeoutMs === undefined
+                ? {}
+                : { requestTimeoutMs: options.rpcRequestTimeoutMs }),
+            ...(options.rpcOperationTimeoutMs === undefined
+                ? {}
+                : { operationTimeoutMs: options.rpcOperationTimeoutMs }),
+        });
     return null;
 }
 const MAX_COMMAND_LINE_BYTES = 256 * 1024;
@@ -145,7 +180,7 @@ export async function runCollaborationCommand(options, output, input = process.s
             output.stderr('pappra: collab run requires --prepared <file> and --capabilities <card>\n');
             return 2;
         }
-        const controller = controllerFor(options.controller);
+        const controller = controllerFor(options.controller, options);
         if (controller === null) {
             output.stderr('pappra: collab run requires --controller <fixture|pi-rpc>\n');
             return 2;

package/dist/cli/commands/continuity.js

@@ -124,10 +124,6 @@ export async function runResumeCommand(options, output) {
     else {
         printDiagnostics(output, result.diagnostics);
     }
-    return result.ok &&
-        result.packet !== null &&
-        result.packet.executionAllowed &&
-        result.packet.verificationStatus === 'current'
-        ? 0
-        : 1;
+    // Reading advisory handoff context does not acquire execution authority.
+    return result.ok && result.packet?.verificationStatus === 'current' ? 0 : 1;
 }

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

@@ -4,6 +4,8 @@ export interface DocsCommandOptions {
     readonly cwd: string;
     readonly action: string | null;
     readonly argument: string | null;
+    readonly targetPath?: string | null;
+    readonly scope?: string | null;
     readonly json: boolean;
     readonly includePrivate: boolean;
     readonly includeArchived: boolean;

package/dist/cli/commands/docs.js

@@ -1,15 +1,18 @@
 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 { docsArchiveReportSchema, docsCheckReportSchema, docsListReportSchema, documentLocationSchema, } from '../../schemas/document.js';
 import { KnowledgeService, } from '../../knowledge/index.js';
-export const docsUsage = 'pappra docs <list|check|archive|scan> [options]\n' +
+export const docsUsage = 'pappra docs <list|check|archive|scan|relocate|forget> [options]\n' +
     '  list   [--include-private] [--include-archived] [--json]\n' +
     '  check  [--include-private] [--json]\n' +
     '  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.';
+    '  relocate <documentId> <workspace-relative-path> [--apply] [--json]\n' +
+    '  forget <documentId> [--scope private|shared] [--apply] [--json]\n\n' +
+    'scan registers existing documents discovered under knowledge.sources; newDocuments is\n' +
+    'only the destination for future authored documents. Without --apply scan only reports\n' +
+    'candidates.';
 async function runDocsScan(options, output, root) {
     const result = await scanDiscoveredDocuments(root, { apply: options.apply });
     if ('message' in result) {
@@ -20,20 +23,37 @@ async function runDocsScan(options, output, root) {
             output.stdout(`${JSON.stringify(result)}\n`);
         }
         else {
-            output.stdout(`Scan candidates: ${result.candidates.length}\n`);
-            for (const candidate of result.candidates) {
-                output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
+            if (result.candidates.length === 0) {
+                output.stdout('No new documents found.\n');
             }
-            output.stdout('Plan only; rerun with --apply to register them.\n');
+            else {
+                output.stdout(`Scan candidates: ${result.candidates.length}\n`);
+                for (const candidate of result.candidates) {
+                    output.stdout(`  ${candidate.kind}  ${candidate.path}\n`);
+                }
+            }
+            printDiagnostics(output, result.diagnostics);
+            for (const action of result.nextActions) {
+                output.stdout(`${action}\n`);
+            }
+            output.stdout(result.ok
+                ? 'Plan only; rerun with --apply to register them.\n'
+                : 'Scan coverage is incomplete; no complete result is claimed.\n');
         }
-        return 0;
+        return result.ok ? 0 : 1;
     }
     if (options.json) {
         output.stdout(`${JSON.stringify(result)}\n`);
     }
     else {
         output.stdout(`Registered ${result.registered.length} document(s).\n`);
+        if (!result.ok) {
+            output.stdout('Scan coverage is incomplete; the registration result is not a complete scan.\n');
+        }
         printDiagnostics(output, result.diagnostics);
+        for (const action of result.nextActions) {
+            output.stdout(`${action}\n`);
+        }
     }
     return result.ok ? 0 : 1;
 }
@@ -75,7 +95,7 @@ export async function runDocsCommand(options, output) {
     if (options.action === null || options.action === 'help') {
         if (options.json) {
             output.stdout(`${JSON.stringify({
-                commands: ['list', 'check', 'archive'],
+                commands: ['list', 'check', 'archive', 'scan', 'relocate', 'forget'],
                 usage: docsUsage,
             })}\n`);
         }
@@ -84,22 +104,67 @@ export async function runDocsCommand(options, output) {
         }
         return 0;
     }
+    if (options.scope !== undefined &&
+        options.scope !== null &&
+        (options.action !== 'forget' ||
+            !['private', 'shared'].includes(options.scope)))
+        return invalidArguments(output, options.json, 'Only docs forget accepts --scope private|shared.');
     const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
     const serviceRoot = resolution.root ?? options.cwd;
-    if (!['list', 'check', 'archive', 'scan'].includes(options.action)) {
+    if (!['list', 'check', 'archive', 'scan', 'relocate', 'forget'].includes(options.action)) {
         return invalidArguments(output, options.json, `unknown docs action: ${options.action}`);
     }
-    if (options.action === 'archive' && options.argument === null) {
-        return invalidArguments(output, options.json, 'docs archive requires a documentId');
+    if (['archive', 'relocate', 'forget'].includes(options.action) &&
+        options.argument === null) {
+        return invalidArguments(output, options.json, `docs ${options.action} requires a documentId`);
     }
-    if (options.action !== 'archive' && options.argument !== null) {
+    if (!['archive', 'relocate', 'forget'].includes(options.action) &&
+        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.action === 'relocate' || options.action === 'forget') &&
+        options.argument !== null) {
+        const location = options.action === 'relocate'
+            ? documentLocationSchema.safeParse({
+                kind: 'workspace',
+                path: options.targetPath,
+            })
+            : null;
+        if (location && !location.success)
+            return invalidArguments(output, options.json, 'docs relocate requires a normalized workspace-relative target path.');
+        if (!options.apply) {
+            const plan = {
+                schema: 'pappra/docs-metadata-plan/1',
+                ok: true,
+                action: options.action,
+                documentId: options.argument,
+                scope: options.scope ?? null,
+                location: location?.success ? location.data : null,
+                applied: false,
+            };
+            output.stdout(options.json
+                ? `${JSON.stringify(plan)}\n`
+                : `Plan only: ${options.action} ${options.argument}; document content is preserved. Rerun with --apply.\n`);
+            return 0;
+        }
+        const service = new KnowledgeService(serviceRoot);
+        const result = location?.success
+            ? await service.relocate(options.argument, location.data)
+            : await service.forget(options.argument, options.scope === 'private' || options.scope === 'shared'
+                ? options.scope
+                : undefined);
+        output.stdout(options.json
+            ? `${JSON.stringify({ schema: 'pappra/docs-metadata-result/1', action: options.action, ...result })}\n`
+            : `${options.action}: ${result.ok ? 'applied' : result.status}\n`);
+        if (!options.json)
+            printDiagnostics(output, result.diagnostics);
+        return result.ok ? 0 : 1;
+    }
     if (options.apply) {
-        return invalidArguments(output, options.json, 'only docs scan accepts --apply');
+        return invalidArguments(output, options.json, 'only docs scan, relocate and forget accept --apply');
     }
     if (options.action === 'archive' && options.argument !== null) {
         const service = new KnowledgeService(serviceRoot);
@@ -142,6 +207,15 @@ export async function runDocsCommand(options, output) {
         else {
             for (const record of result.records)
                 printDocument(output, record);
+            if (result.records.length === 0 && !options.includePrivate && result.ok) {
+                const command = options.includeArchived
+                    ? 'pappra docs list --include-private --include-archived'
+                    : 'pappra docs list --include-private';
+                output.stdout(`No documents in the default view. Private documents are hidden; run: ${command}\n`);
+                if (!options.includeArchived) {
+                    output.stdout('Archived documents also remain hidden; add --include-archived to include them.\n');
+                }
+            }
             printDiagnostics(output, result.diagnostics);
         }
         return result.ok ? 0 : 1;

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

@@ -4,7 +4,7 @@ export declare const hostUsage: string;
 export interface HostCommandOptions {
     readonly cwd: string;
     readonly json: boolean;
-    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'verify' | 'bundle' | 'mcp' | 'probe' | null;
+    readonly action: 'detect' | 'describe' | 'plan' | 'install' | 'uninstall' | 'verify' | 'bundle' | 'mcp' | 'probe' | null;
     readonly host: HostName | null;
     readonly hostRoot: string | null;
     readonly hostVersion: string | null;
@@ -13,6 +13,12 @@ export interface HostCommandOptions {
     readonly subAction: string | null;
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
+    /** Explicit private bootstrap binding; Pi bundle exports only. */
+    readonly bootstrapConfig: string | null;
+    /** Explicit validated task/session binding; recovery exports are Pi-only. */
+    readonly recoveryConfig: string | null;
+    /** Opt-in Pi session-transition command extension; it is not native takeover. */
+    readonly transitionExtension: boolean;
     readonly marketplace: boolean;
     readonly scope: 'project' | 'user' | null;
 }