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

package/dist/schemas/document.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type LocalProcessIdentity } from '../infra/process-identity.js';
 export declare const DOCUMENT_SCHEMA = "pappra/document/1";
 export declare const DOCUMENT_CATALOG_SCHEMA = "pappra/document-catalog/1";
 export declare const DOCUMENT_WRITE_PROPOSAL_SCHEMA = "pappra/document-write-proposal/1";
@@ -115,6 +116,65 @@ export declare const documentRecordSchema: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 export type DocumentRecord = z.infer<typeof documentRecordSchema>;
+export declare const documentRecordFileSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"pappra/document-record-file/1">;
+    workspaceId: z.ZodUUID;
+    record: z.ZodObject<{
+        schema: z.ZodLiteral<"pappra/document/1">;
+        documentId: z.ZodUUID;
+        location: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"workspace">;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"source">;
+            sourceId: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        kind: z.ZodEnum<{
+            architecture: "architecture";
+            checkpoint: "checkpoint";
+            decision: "decision";
+            delivery: "delivery";
+            generated: "generated";
+            plan: "plan";
+            research: "research";
+            review: "review";
+            rule: "rule";
+        }>;
+        lifecycle: z.ZodEnum<{
+            active: "active";
+            archived: "archived";
+            superseded: "superseded";
+        }>;
+        maturity: z.ZodEnum<{
+            draft: "draft";
+            reviewed: "reviewed";
+        }>;
+        taskId: z.ZodNullable<z.ZodString>;
+        owner: z.ZodEnum<{
+            agent: "agent";
+            generator: "generator";
+            human: "human";
+        }>;
+        digest: z.ZodString;
+        sources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"document">;
+            documentId: z.ZodUUID;
+            digest: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            repositoryId: z.ZodString;
+            path: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        supersededBy: z.ZodNullable<z.ZodUUID>;
+        lastReviewedAt: z.ZodNullable<z.ZodISODateTime>;
+        visibility: z.ZodEnum<{
+            private: "private";
+            shareable: "shareable";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const documentCatalogSchema: z.ZodObject<{
     schema: z.ZodLiteral<"pappra/document-catalog/1">;
     workspaceId: z.ZodUUID;
@@ -335,6 +395,7 @@ export declare const knowledgeLockSchema: z.ZodObject<{
         "write-document": "write-document";
     }>;
     pid: z.ZodNumber;
+    process_identity: z.ZodOptional<z.ZodCustom<LocalProcessIdentity, LocalProcessIdentity>>;
     createdAt: z.ZodISODateTime;
 }, z.core.$strict>;
 export type KnowledgeLock = z.infer<typeof knowledgeLockSchema>;

package/dist/schemas/document.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isLocalProcessIdentity, } from '../infra/process-identity.js';
 import { isPortableRelativePath, normalizePortableRelativePath, } from './paths.js';
 export const DOCUMENT_SCHEMA = 'pappra/document/1';
 export const DOCUMENT_CATALOG_SCHEMA = 'pappra/document-catalog/1';
@@ -102,6 +103,11 @@ export const documentRecordSchema = documentRecordBaseSchema.superRefine((record
         });
     }
 });
+export const documentRecordFileSchema = z.strictObject({
+    schema: z.literal('pappra/document-record-file/1'),
+    workspaceId: z.uuid(),
+    record: documentRecordSchema,
+});
 export const documentCatalogSchema = z.strictObject({
     schema: z.literal(DOCUMENT_CATALOG_SCHEMA),
     workspaceId: z.uuid(),
@@ -202,6 +208,9 @@ export const knowledgeLockSchema = z.strictObject({
     token: z.uuid(),
     operation: knowledgeOperationSchema,
     pid: z.number().int().positive(),
+    process_identity: z
+        .custom(isLocalProcessIdentity)
+        .optional(),
     createdAt: z.iso.datetime({ offset: true }),
 });
 export const knowledgeJournalSchema = z.strictObject({

package/dist/schemas/errors.d.ts

@@ -29,6 +29,7 @@ export declare const diagnosticCodes: {
     readonly initApplyFailed: 'init_apply_failed';
     readonly initApplyResidual: 'init_apply_residual';
     readonly initRuntimeSourceRequired: 'init_runtime_source_required';
+    readonly runtimeStateIncompatible: 'runtime_state_incompatible';
     readonly initCancelled: 'init_cancelled';
     readonly fileInvalidEncoding: 'file_invalid_encoding';
     readonly configMissing: 'config_missing';

package/dist/schemas/errors.js

@@ -29,6 +29,7 @@ export const diagnosticCodes = {
     initApplyFailed: 'init_apply_failed',
     initApplyResidual: 'init_apply_residual',
     initRuntimeSourceRequired: 'init_runtime_source_required',
+    runtimeStateIncompatible: 'runtime_state_incompatible',
     initCancelled: 'init_cancelled',
     fileInvalidEncoding: 'file_invalid_encoding',
     configMissing: 'config_missing',

package/dist/schemas/host.d.ts

@@ -434,3 +434,27 @@ export declare const hostInstallManifestSchema: z.ZodObject<{
     trustRequired: z.ZodBoolean;
 }, z.core.$strict>;
 export type HostInstallManifest = z.infer<typeof hostInstallManifestSchema>;
+export declare const hostUninstallResultSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"pappra/host-uninstall/1">;
+    host: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        pi: "pi";
+    }>;
+    hostRoot: z.ZodString;
+    ok: z.ZodBoolean;
+    status: z.ZodEnum<{
+        conflict: "conflict";
+        failed: "failed";
+        partial: "partial";
+        planned: "planned";
+        removed: "removed";
+        unchanged: "unchanged";
+    }>;
+    plannedFiles: z.ZodArray<z.ZodString>;
+    removedFiles: z.ZodArray<z.ZodString>;
+    retainedPaths: z.ZodArray<z.ZodString>;
+    quarantinedLocks: z.ZodArray<z.ZodString>;
+    diagnostics: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strict>;
+export type HostUninstallResult = z.infer<typeof hostUninstallResultSchema>;

package/dist/schemas/host.js

@@ -201,3 +201,22 @@ export const hostInstallManifestSchema = z.strictObject({
     reloadRequired: z.boolean(),
     trustRequired: z.boolean(),
 });
+export const hostUninstallResultSchema = z.strictObject({
+    schema: z.literal('pappra/host-uninstall/1'),
+    host: hostNameSchema,
+    hostRoot: absolutePathSchema,
+    ok: z.boolean(),
+    status: z.enum([
+        'planned',
+        'removed',
+        'unchanged',
+        'partial',
+        'conflict',
+        'failed',
+    ]),
+    plannedFiles: z.array(z.string().min(1).max(2048)).max(512),
+    removedFiles: z.array(z.string().min(1).max(2048)).max(512),
+    retainedPaths: z.array(absolutePathSchema).max(512),
+    quarantinedLocks: z.array(absolutePathSchema).max(32),
+    diagnostics: z.array(z.unknown()).max(32),
+});

package/dist/schemas/install.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
-export declare const RUNTIME_MANIFEST_SCHEMA = "pappra/runtime-manifest/1";
+import { type LocalProcessIdentity } from '../infra/process-identity.js';
+export declare const RUNTIME_MANIFEST_SCHEMA = "pappra/runtime-manifest/3";
+export declare const RUNTIME_DIGEST_SCHEME = "sha256-utf8-byte-order-v1";
 export declare const WORKSPACE_MANIFEST_SCHEMA = "pappra/install-manifest/1";
 export declare const INSTALL_JOURNAL_SCHEMA = "pappra/install-journal/1";
 export declare const LOCK_SCHEMA = "pappra/install-lock/1";
@@ -15,11 +17,13 @@ export declare const installLockSchema: z.ZodObject<{
         "install-runtime": "install-runtime";
         "remove-runtime": "remove-runtime";
         "rollback-workspace-files": "rollback-workspace-files";
+        "set-auto-resume": "set-auto-resume";
         "uninstall-workspace-files": "uninstall-workspace-files";
         "update-machine-runtime": "update-machine-runtime";
     }>;
     target: z.ZodString;
     pid: z.ZodNumber;
+    process_identity: z.ZodOptional<z.ZodCustom<LocalProcessIdentity, LocalProcessIdentity>>;
     createdAt: z.ZodISODateTime;
 }, z.core.$strict>;
 export type InstallLock = z.infer<typeof installLockSchema>;
@@ -44,7 +48,7 @@ export declare const runtimeSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>], "kind">;
 export type RuntimeSource = z.infer<typeof runtimeSourceSchema>;
 export declare const runtimeManifestSchema: z.ZodObject<{
-    schema: z.ZodLiteral<"pappra/runtime-manifest/1">;
+    schema: z.ZodLiteral<"pappra/runtime-manifest/3">;
     installId: z.ZodUUID;
     packageName: z.ZodString;
     runtimeVersion: z.ZodString;
@@ -70,6 +74,8 @@ export declare const runtimeManifestSchema: z.ZodObject<{
         digest: z.ZodString;
     }, z.core.$strict>], "kind">;
     packageDigest: z.ZodString;
+    digestScheme: z.ZodLiteral<"sha256-utf8-byte-order-v1">;
+    sourceFingerprint: z.ZodString;
     smoke: z.ZodObject<{
         argv: z.ZodArray<z.ZodString>;
         exitCode: z.ZodNumber;

package/dist/schemas/install.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
-export const RUNTIME_MANIFEST_SCHEMA = 'pappra/runtime-manifest/1';
+import { isLocalProcessIdentity, } from '../infra/process-identity.js';
+export const RUNTIME_MANIFEST_SCHEMA = 'pappra/runtime-manifest/3';
+export const RUNTIME_DIGEST_SCHEME = 'sha256-utf8-byte-order-v1';
 export const WORKSPACE_MANIFEST_SCHEMA = 'pappra/install-manifest/1';
 export const INSTALL_JOURNAL_SCHEMA = 'pappra/install-journal/1';
 export const LOCK_SCHEMA = 'pappra/install-lock/1';
@@ -24,9 +26,15 @@ export const installLockSchema = z.strictObject({
         'uninstall-workspace-files',
         'remove-runtime',
         'update-machine-runtime',
+        // Private hook preference toggle guarded by the workspace lock; shared
+        // configuration is never rewritten by this operation.
+        'set-auto-resume',
     ]),
     target: z.string().min(1).max(4096),
     pid: z.number().int().positive(),
+    process_identity: z
+        .custom(isLocalProcessIdentity)
+        .optional(),
     createdAt: z.iso.datetime({ offset: true }),
 });
 export const runtimeSourceSchema = z.discriminatedUnion('kind', [
@@ -61,6 +69,8 @@ export const runtimeManifestSchema = z.strictObject({
     executable: pathSchema,
     source: runtimeSourceSchema,
     packageDigest: digestSchema,
+    digestScheme: z.literal(RUNTIME_DIGEST_SCHEME),
+    sourceFingerprint: digestSchema,
     smoke: z.strictObject({
         argv: z.array(z.string().max(4096)).max(16),
         exitCode: z.number().int(),

package/dist/schemas/managed-pi-execution.d.ts

@@ -0,0 +1,16 @@
+/** Persisted execution pins shared by orchestration and native host adapters. */
+export declare const MANAGED_PI_EXECUTION_SCOPE_SCHEMA = "pappra/managed-pi-execution-scope/1";
+export interface ManagedPiExecutionScope {
+    readonly schema: typeof MANAGED_PI_EXECUTION_SCOPE_SCHEMA;
+    readonly task_id: string;
+    readonly task_root: string;
+    readonly session_id: string;
+    readonly cwd: string;
+    readonly subtask_id: string;
+    readonly attempt: number;
+    readonly owner_epoch: number;
+    readonly claim_epochs: readonly {
+        readonly claim_id: string;
+        readonly resource_epoch: number;
+    }[];
+}

package/dist/schemas/managed-pi-execution.js

@@ -0,0 +1,2 @@
+/** Persisted execution pins shared by orchestration and native host adapters. */
+export const MANAGED_PI_EXECUTION_SCOPE_SCHEMA = 'pappra/managed-pi-execution-scope/1';

package/dist/schemas/outcome.d.ts

@@ -1,15 +1,19 @@
 import type { DiagnosticCode } from './errors.js';
 /** Expected rejection; unexpected exceptions are converted at application boundaries. */
-export type Outcome<T> = {
-    readonly ok: true;
-    readonly value: T;
-} | {
+export interface ExpectedFailure {
     readonly ok: false;
     readonly code: DiagnosticCode;
     readonly message: string;
     readonly retryable: boolean;
     readonly nextAction: string | null;
-};
+}
+/** Value-bearing boundaries share one shape; protocol-specific failures retain their typed fields. */
+export type Outcome<T, Rejection extends {
+    readonly ok: false;
+} = ExpectedFailure> = {
+    readonly ok: true;
+    readonly value: T;
+} | Rejection;
 export interface FailureOptions {
     readonly retryable?: boolean;
     readonly nextAction?: string | null;

package/dist/workspace/config-file.js

@@ -1,3 +1,4 @@
+import { object as isRecord } from '../infra/validation.js';
 import { join, resolve } from 'node:path';
 import { createDiagnostic, hasErrors, pointer, } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
@@ -35,9 +36,6 @@ function issueDiagnostics(issues, source) {
     }
     return diagnostics;
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /**
  * Reads, decodes, validates, and semantically checks one strict JSON
  * configuration file. Missing configuration is reported instead of defaulted.

package/dist/workspace/documents.js

@@ -250,6 +250,16 @@ export async function discoverDocuments(input) {
                 if (entry.isDirectory()) {
                     if (depth < depthLimit)
                         await visit(child, depth + 1);
+                    else {
+                        truncated = true;
+                        diagnostics.push(createDiagnostic({
+                            code: diagnosticCodes.discoveryLimitReached,
+                            severity: 'warning',
+                            message: `Document directory depth limit reached: ${child}`,
+                            source: child,
+                            hint: 'Increase the explicit discovery depth or narrow the knowledge source.',
+                        }));
+                    }
                     continue;
                 }
                 if (!entry.isFile() || !isMarkdown(child))
@@ -294,7 +304,7 @@ export async function discoverDocuments(input) {
         const docs = join(directory, 'docs');
         const docsObservation = await observePath(docs);
         if (docsObservation.kind === 'directory') {
-            await scanDirectory(docs, 3, repository === null ? 'directory-scan' : 'repository-scan', `${declaredPrefix}:docs`, containmentRoot, null);
+            await scanDirectory(docs, Math.max(3, options.scanDepth), repository === null ? 'directory-scan' : 'repository-scan', `${declaredPrefix}:docs`, containmentRoot, null);
         }
     };
     if (config !== null) {
@@ -342,7 +352,7 @@ export async function discoverDocuments(input) {
                 await addDocument(real, 'workspace-config', declaredBy, root);
             }
             else if (resolvedObservation.kind === 'directory') {
-                await scanDirectory(real, 3, 'workspace-config', declaredBy, root, null);
+                await scanDirectory(real, Math.max(3, options.scanDepth), 'workspace-config', declaredBy, root, null);
             }
         }
     }

package/dist/workspace/repositories.d.ts

@@ -1,6 +1,7 @@
 import type { Diagnostic } from '../schemas/diagnostics.js';
 import { type WorkspaceConfig } from '../schemas/workspace.js';
 import type { MachineConfig } from '../schemas/machine.js';
+import { type GitObservationScope } from '../infra/git.js';
 import type { DiscoveredRepository, NormalizedDiscoveryOptions, UnresolvedRepository } from './types.js';
 export interface RepositoryDiscoveryInput {
     readonly root: string;
@@ -8,6 +9,12 @@ export interface RepositoryDiscoveryInput {
     readonly machine: MachineConfig | null;
     readonly configPath: string;
     readonly options: NormalizedDiscoveryOptions;
+    /**
+     * One operation's Git probe scope. Discovery and a later identity probe of the
+     * same checkout must share it, otherwise identical repository probes are
+     * spawned twice. Callers that omit it get a scope scoped to this discovery.
+     */
+    readonly observations?: GitObservationScope;
 }
 export interface RepositoryDiscoveryOutput {
     readonly repositories: readonly DiscoveredRepository[];

package/dist/workspace/repositories.js

@@ -4,9 +4,12 @@ import { createDiagnostic, pointer } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
 import { externalRepositoryId, isExternalRepositoryPath, isPathInside, resolvePortableRelativePath, samePath, toWorkspaceRelativePath, } from '../schemas/paths.js';
 import { normalizedExcludes, } from '../schemas/workspace.js';
-import { inspectGitRepository, } from '../infra/git.js';
+import { createGitObservationScope, } from '../infra/git.js';
 import { observePath, resolveRealpath } from '../infra/fs.js';
 import { isExcludedPath, isHiddenSegment } from './ignore.js';
+function probeScope(input) {
+    return input.observations ?? createGitObservationScope();
+}
 function failureDiagnostic(failure, source, location) {
     return createDiagnostic({
         code: failure.code,
@@ -185,7 +188,7 @@ async function resolveConfiguredRepository(input, repositoryIndex) {
         }));
         return { repository: null, unresolved: unresolved(), diagnostics };
     }
-    const inspected = await inspectGitRepository(candidateRoot, {
+    const inspected = await probeScope(input).repository(candidateRoot, {
         timeoutMs: options.gitTimeoutMs,
     });
     if (!inspected.ok) {
@@ -231,6 +234,12 @@ function scanRepository(input, git) {
  */
 export async function discoverRepositories(input) {
     const { config, configPath, options, root } = input;
+    // One scope per discovery: explicit declarations, the root probe and any scan
+    // share the same immutable repository observations.
+    const decorated = {
+        ...input,
+        observations: input.observations ?? createGitObservationScope(),
+    };
     const diagnostics = [];
     const repositories = [];
     const unresolved = [];
@@ -260,7 +269,7 @@ export async function discoverRepositories(input) {
     };
     if (config !== null) {
         for (const index of config.repositories.keys()) {
-            const resolved = await resolveConfiguredRepository(input, index);
+            const resolved = await resolveConfiguredRepository(decorated, index);
             diagnostics.push(...resolved.diagnostics);
             if (resolved.repository !== null)
                 addRepository(resolved.repository);
@@ -271,7 +280,7 @@ export async function discoverRepositories(input) {
     const rootGitEntry = await observePath(join(root, '.git'));
     if (rootGitEntry.kind === 'directory' || rootGitEntry.kind === 'file') {
         stopsAtRepositories = true;
-        const inspected = await inspectGitRepository(root, {
+        const inspected = await probeScope(decorated).repository(root, {
             timeoutMs: options.gitTimeoutMs,
         });
         if (inspected.ok) {
@@ -324,7 +333,7 @@ export async function discoverRepositories(input) {
             }
             const gitEntry = await observePath(join(directory, '.git'));
             if (gitEntry.kind === 'directory' || gitEntry.kind === 'file') {
-                const inspected = await inspectGitRepository(directory, {
+                const inspected = await probeScope(decorated).repository(directory, {
                     timeoutMs: options.gitTimeoutMs,
                 });
                 if (inspected.ok) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.13",
-  "description": "Portable workspace knowledge and continuity for coding agents.",
+  "version": "0.1.0-beta.18",
+  "description": "Portable coding-agent workspaces with knowledge, continuity, code navigation and optional collaboration.",
   "publishConfig": {
     "access": "public"
   },
@@ -19,33 +19,13 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./collab": {
-      "types": "./dist/collab/index.d.ts",
-      "import": "./dist/collab/index.js"
-    },
-    "./collab/admission": {
-      "types": "./dist/collab/admission.d.ts",
-      "import": "./dist/collab/admission.js"
-    },
-    "./hosts": {
-      "types": "./dist/hosts/index.d.ts",
-      "import": "./dist/hosts/index.js"
-    },
-    "./doctor": {
-      "types": "./dist/app/doctor.d.ts",
-      "import": "./dist/app/doctor.js"
-    },
-    "./init": {
-      "types": "./dist/app/init.d.ts",
-      "import": "./dist/app/init.js"
-    },
-    "./collaboration": {
-      "types": "./dist/app/collaboration.d.ts",
-      "import": "./dist/app/collaboration.js"
+    "./workspace": {
+      "types": "./dist/workspace/index.d.ts",
+      "import": "./dist/workspace/index.js"
     },
-    "./install": {
-      "types": "./dist/install/index.d.ts",
-      "import": "./dist/install/index.js"
+    "./knowledge": {
+      "types": "./dist/knowledge/index.d.ts",
+      "import": "./dist/knowledge/index.js"
     },
     "./continuity": {
       "types": "./dist/continuity/index.d.ts",
@@ -55,17 +35,37 @@
       "types": "./dist/code/index.d.ts",
       "import": "./dist/code/index.js"
     },
-    "./knowledge": {
-      "types": "./dist/knowledge/index.d.ts",
-      "import": "./dist/knowledge/index.js"
-    },
     "./schemas": {
       "types": "./dist/schemas/index.d.ts",
       "import": "./dist/schemas/index.js"
     },
-    "./workspace": {
-      "types": "./dist/workspace/index.d.ts",
-      "import": "./dist/workspace/index.js"
+    "./install": {
+      "types": "./dist/install/index.d.ts",
+      "import": "./dist/install/index.js"
+    },
+    "./hosts": {
+      "types": "./dist/hosts/index.d.ts",
+      "import": "./dist/hosts/index.js"
+    },
+    "./init": {
+      "types": "./dist/init.d.ts",
+      "import": "./dist/init.js"
+    },
+    "./doctor": {
+      "types": "./dist/doctor.d.ts",
+      "import": "./dist/doctor.js"
+    },
+    "./collab": {
+      "types": "./dist/collab/index.d.ts",
+      "import": "./dist/collab/index.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental/index.d.ts",
+      "import": "./dist/experimental/index.js"
+    },
+    "./experimental/pi": {
+      "types": "./dist/experimental/pi.d.ts",
+      "import": "./dist/experimental/pi.js"
     },
     "./package.json": "./package.json"
   },

package/skills/pappra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pappra
-description: Use Pappra workspace knowledge, checkpoint/resume, and selected-repository code intelligence from any supported coding agent. Use when a task needs durable handoff context, workspace documents, or bounded code navigation.
+description: Use Pappra workspace knowledge, checkpoint/resume, selected-repository code intelligence, and task-scoped cross-harness collaboration from any supported coding agent. Use when a task needs durable handoff context, workspace documents, bounded code navigation, or a visible/direct multi-agent collaboration workflow.
 ---
 
 # Pappra
@@ -20,15 +20,28 @@ index, or new writer.
    the workspace selected by the current root. Never infer a workspace from an
    unrelated session. `pappra docs scan --apply` registers discovered documents;
    `pappra runtime install --apply` keeps a durable copy of this package.
-5. For a new bounded collaboration request, build an explicit
-   `pappra/collaboration-goal/1` from the user's objective and named choices,
-   run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
-   card, then use `pappra collab run` with the reviewed controller. `--controller
-pi-rpc` launches a real owned Pi session and is verified for Pi 1.3.0. Never
-   turn prose into identity, approval, or capability claims.
+5. For task-scoped collaboration, read `references/environment.md` first to
+   choose direct versus visible Herdr operation, bootstrap or reuse the
+   receiving instance, and bind its routing identity. Then read
+   `references/collaboration.md` and build the shared strict
+   `pappra/collaboration-goal/1` from explicit choices. The installed CLI accepts
+   `pappra collab prepare --goal <file> --domain-root <dir>`; it has no preview
+   mode, so it mutates task state, claims resources and registers the initial
+   ASSIGN once authorized. MCP `collab_prepare` accepts `{ domainRoot, goal }`
+   and rejects the retired flat objective form. Neither prepares a capability
+   card; derive and preflight actual runtime evidence separately, and notify the
+   already-registered ASSIGN rather than sending a duplicate. Visible peers are
+   the default collaboration channel; the owned Pi `pi-rpc` run remains a
+   separate explicit option, and fixtures are explicit only. Never turn prose
+   into identity, approval, or capability claims.
 
 ## One-request collaboration
 
+Visible collaboration uses `references/environment.md` plus the persisted
+message/notify loop in `references/collaboration.md`. The owned `collab run`
+flow described here is the separate Pi RPC option, not a substitute for a
+visible participant.
+
 `pappra collab prepare --goal <file> --domain-root <dir>` requires an explicit
 shared domain. It validates the canonical domain/tasks/task/private namespace
 before writing any task metadata and again around each write, so a task-root or
@@ -61,6 +74,14 @@ No approval is auto-answered, no cancel is inferred from an acknowledgement, and
 arbitrary PID is adopted. Do not launch a model or real user session without
 the task's explicit authorization.
 
+## Recovery and parallel work
+
+Use `pappra collab work-run --request <abs-request.json>` for a read-only plan and add `--apply` only when the existing assignments, current capability cards, coordinator authority, resource claims and visible participant binding are ready. Work-run notifies only registered participants; it does not create sessions, merge, accept reports, or replay ambiguous delivery.
+
+Use `pappra collab recovery-run --request <abs-request.json>` to inspect one guarded recovery action; add `--apply` only with exact current session/cwd/harness/pane and a digest-pinned task-local binding. Recovery is a bounded single wake, not generic outage recovery: there is no reconnect trigger, hidden worker, approval automation, or replay after an unknown effect.
+
+For an explicitly selected Pi package, `pappra host bundle --host pi --out <new-private-dir> --recovery-config <abs-private-config.json>` exports the recovery extension and its private sibling config. Add `--transition-extension` to export the separate `/collab-transition` command extension. Exports do not install, trust, enable, load, launch, or transfer anything; review and install packages explicitly. Native quiescence and interactive Pi session takeover remain unsupported, and task retirement is not native session archive.
+
 ## Boundaries
 
 - Hooks are local and bounded. They do not read transcripts, run commands,