@xfey/tutti 0.1.28 → 0.1.30

package/node_modules/@tutti/relay-client/dist/host-control.js

@@ -20,6 +20,9 @@ function registrationUrl(relayUrl) {
 function joinTokenUrl(relayUrl) {
     return new URL("/host-control/v1/join-token", relayUrl);
 }
+function archiveProjectUrl(relayUrl) {
+    return new URL("/host-control/v1/projects/archive", relayUrl);
+}
 function uploadResolveUrl(relayUrl) {
     return new URL("/host-control/v1/uploads/resolve", relayUrl);
 }
@@ -82,6 +85,19 @@ function createRefreshJoinTokenPayload(options) {
     }
     return payload;
 }
+function createArchiveRelayProjectPayload(options) {
+    return {
+        project_identity: {
+            source: "git_config",
+            project_id: options.projectId,
+        },
+        relay_project_ref: options.relayProjectRef,
+        host_auth: {
+            kind: "host_registration_secret_v1",
+            secret: options.hostRegistrationSecret,
+        },
+    };
+}
 function createResolveRelayUploadPayload(options) {
     return {
         project_identity: {
@@ -116,7 +132,7 @@ function relayErrorCodeFromBody(value) {
     }
     return stringField(value.error, "code");
 }
-async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs, externalSignal) {
     const controller = new AbortController();
     const timeout = setTimeout(() => {
         controller.abort();
@@ -124,7 +140,9 @@ async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
     try {
         return await fetchImpl(url, {
             ...init,
-            signal: controller.signal,
+            signal: externalSignal === undefined
+                ? controller.signal
+                : AbortSignal.any([controller.signal, externalSignal]),
         });
     }
     finally {
@@ -147,6 +165,21 @@ function assertRefreshJoinTokenResponse(value) {
     }
     return value;
 }
+function assertArchiveRelayProjectResponse(value) {
+    if (!isRecord(value) ||
+        stringField(value, "command_id") === undefined ||
+        !isRecord(value.disposition)) {
+        throw new RelayHostControlClientError("relay_registration_failed", "Relay project archive response is invalid", false);
+    }
+    const kind = stringField(value.disposition, "kind");
+    if (kind !== "archived" && kind !== "already_archived" && kind !== "interrupted") {
+        throw new RelayHostControlClientError("relay_registration_failed", "Relay project archive disposition is invalid", false);
+    }
+    if (kind === "interrupted" && value.disposition.retry_with_new_command_id !== true) {
+        throw new RelayHostControlClientError("relay_registration_failed", "Relay project archive disposition is invalid", false);
+    }
+    return value;
+}
 function assertResolveRelayUploadResponse(value) {
     if (!isRecord(value) || !isRecord(value.upload) || !isRecord(value.get)) {
         throw new RelayHostControlClientError("relay_registration_failed", "Relay upload resolve response is invalid", false);
@@ -176,7 +209,7 @@ export async function registerRelayHostConnection(options) {
                     issued_at: issuedAt.toISOString(),
                     payload: createRegisterPayload(options),
                 }),
-            }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS, options.signal);
         }
         catch {
             throw new RelayHostControlClientError("relay_unavailable", `Cannot reach Relay at ${options.relayUrl}`, true);
@@ -223,6 +256,40 @@ export async function refreshRelayJoinToken(options) {
     }
     return assertRefreshJoinTokenResponse(await response.json());
 }
+export async function archiveRelayProject(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const commandId = options.commandId ?? createIdempotencyKey();
+    const issuedAt = options.issuedAt ?? new Date();
+    let response;
+    try {
+        response = await fetchWithTimeout(fetchImpl, archiveProjectUrl(options.relayUrl), {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                command_id: commandId,
+                issued_at: issuedAt.toISOString(),
+                payload: createArchiveRelayProjectPayload(options),
+            }),
+        }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    }
+    catch {
+        throw new RelayHostControlClientError("relay_unavailable", `Cannot reach Relay at ${options.relayUrl}`, true);
+    }
+    if (!response.ok) {
+        let relayErrorCode;
+        try {
+            relayErrorCode = relayErrorCodeFromBody(await response.json());
+        }
+        catch {
+            relayErrorCode = undefined;
+        }
+        throw new RelayHostControlClientError(response.status >= 500 ? "relay_unavailable" : "relay_registration_failed", `Relay project archive failed with HTTP ${response.status}`, response.status >= 500, response.status, relayErrorCode);
+    }
+    return assertArchiveRelayProjectResponse(await response.json());
+}
 export async function resolveRelayUpload(options) {
     const fetchImpl = options.fetch ?? fetch;
     const response = await (async () => {

package/node_modules/@tutti/relay-client/dist/tunnel-types.d.ts

@@ -35,7 +35,7 @@ export type RelayHostTunnelStreamRequestHandler = (request: RelayHostTunnelReque
 export type RelayHostTunnelWebSocketLike = {
     on(event: "open", listener: () => void): void;
     on(event: "message", listener: (data: unknown) => void): void;
-    on(event: "close", listener: () => void): void;
+    on(event: "close", listener: (code?: number, reason?: unknown) => void): void;
     on(event: "error", listener: (error: unknown) => void): void;
     send(data: string, callback?: (error?: Error) => void): void;
     close(code?: number, reason?: string): void;
@@ -46,9 +46,13 @@ export type RelayHostTunnelConnector = (options: {
 }) => RelayHostTunnelWebSocketLike;
 export type RelayHostTunnelHandle = {
     connected: Promise<void>;
-    closed: Promise<void>;
+    closed: Promise<RelayHostTunnelCloseResult>;
     close: (code?: number, reason?: string) => void;
 };
+export type RelayHostTunnelCloseResult = {
+    code?: number;
+    reason?: string;
+};
 export type ConnectRelayHostTunnelOptions = {
     tunnelUrl: string;
     relayProjectRef: RelayProjectRef;

package/node_modules/@tutti/relay-client/dist/tunnel.js

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { redactAndTruncateText } from "@tutti/shared/utils";
 import { chunkToBase64, internalErrorResponse, parseHostRequestFrame, parseHostStreamCancelFrame, sendFrame, sendResponse, } from "./tunnel-frames.js";
 const loadNativeModule = createRequire(import.meta.url);
 function defaultConnector(options) {
@@ -123,7 +124,7 @@ export function connectRelayHostTunnel(options) {
             rejectConnected(error instanceof Error ? error : new Error("Relay host tunnel failed"));
         }
     });
-    socket.on("close", () => {
+    socket.on("close", (code, reason) => {
         for (const controller of streamControllers.values()) {
             controller.abort();
         }
@@ -131,7 +132,17 @@ export function connectRelayHostTunnel(options) {
         if (!connectedSettled) {
             rejectConnected(new Error("Relay host tunnel closed before it opened"));
         }
-        resolveClosed();
+        const normalizedReason = typeof reason === "string"
+            ? reason
+            : Buffer.isBuffer(reason)
+                ? reason.toString("utf8")
+                : undefined;
+        resolveClosed({
+            ...(code === undefined ? {} : { code }),
+            ...(normalizedReason === undefined || normalizedReason === ""
+                ? {}
+                : { reason: redactAndTruncateText(normalizedReason, 120) }),
+        });
     });
     return {
         connected,

package/node_modules/@tutti/shared/dist/schemas/api/clarifications.d.ts

@@ -569,6 +569,27 @@ export declare const SendClarificationRoundMessageResultSchema: import("@sinclai
                 }>>>;
                 primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
+            task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                kind: import("@sinclair/typebox").TLiteral<"task_result">;
+                status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+                title: import("@sinclair/typebox").TString;
+                task_id: import("@sinclair/typebox").TString;
+                task_title: import("@sinclair/typebox").TString;
+                result_key: import("@sinclair/typebox").TString;
+                summary: import("@sinclair/typebox").TString;
+                module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                    path: import("@sinclair/typebox").TString;
+                    name: import("@sinclair/typebox").TString;
+                    group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                    size_bytes: import("@sinclair/typebox").TInteger;
+                    media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                }>>>;
+                error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
             artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
                 title: import("@sinclair/typebox").TString;

package/node_modules/@tutti/shared/dist/schemas/api/index.d.ts

@@ -6,7 +6,7 @@ export { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchema, Pr
 export { ProjectTimelineChangeStatusSchema, ProjectTimelineClarificationTraceSchema, ProjectTimelineDecisionSummarySchema, ProjectTimelineItemKindSchema, ProjectTimelineItemSchema, ProjectTimelineItemStatusSchema, ProjectTimelineResponseSchema, ProjectTimelineSourceSnippetSchema, ProjectTimelineTaskUpdateStateSchema, ProjectTimelineTraceCardSchema, ProjectTimelineTraceLinkSchema, ProjectTimelineTraceToneSchema, } from "./project-timeline.js";
 export { MAX_REFERENCE_STAGED_UPLOAD_BYTES, MAX_SKILL_ZIP_STAGED_UPLOAD_BYTES, MAX_STAGED_UPLOAD_BYTES, PresignedUploadPutSchema, ReferenceFileStartRelayUploadPayloadSchema, ReferenceStagedUploadReferenceProperties, RelayUploadProjectionSchema, RelayUploadPurposeSchema, Sha256DigestSchema, SkillZipStartRelayUploadPayloadSchema, SkillZipStagedUploadReferenceProperties, StagedUploadReferenceProperties, StagedUploadReferenceSchema, StartRelayUploadBodySchema, StartRelayUploadDispositionSchema, StartRelayUploadPayloadSchema, StartRelayUploadResponseSchema, StartRelayUploadResultSchema, maxStagedUploadBytesForPurpose, } from "./uploads.js";
 export { MarkReadBodySchema, MarkReadDispositionSchema, MarkReadPayloadSchema, MarkReadResponseSchema, MarkReadResultSchema, ReadStateScopeProjectionSchema, ReadStateScopeSchema, ReadStateSummaryProjectionSchema, } from "./read-state.js";
-export { GetMessagesRequestSchema, MessageAuthorSchema, MessageCreatedEventPayloadSchema, MessageKindSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, MessageRefsSchema, MessageScopeSchema, MessageWindowSchema, ReferenceFileCategorySchema, SendMainChatMessageBodySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResponseSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, WorklistCompileRefSchema, WorklistFeedbackItemSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackRefSchema, } from "./messages.js";
+export { GetMessagesRequestSchema, MessageAuthorSchema, MessageCreatedEventPayloadSchema, MessageKindSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, MessageRefsSchema, MessageScopeSchema, MessageWindowSchema, ReferenceFileCategorySchema, SendMainChatMessageBodySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResponseSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, TaskResultRefSchema, WorklistCompileRefSchema, WorklistFeedbackItemSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackRefSchema, } from "./messages.js";
 export { CheckSkipReasonCodeSchema, ExternalSideEffectSummaryProjectionSchema, GetRecoverySummariesRequestSchema, GetRecoverySummariesResponseSchema, GetRecoverySummaryResponseSchema, RecoverySummaryProjectionSchema, ResultAnchorSchema, RunLineageSchema, RunResultProjectionSchema, ScratchpadProjectionSchema, ScratchpadReceiptProjectionSchema, TaskContractProjectionSchema, TaskDetailProjectionSchema, TaskDetailResultProjectionSchema, TaskModuleProjectionSchema, TaskProjectionSchema, TaskRunResultsPageSchema, TaskStatusSchema, WorklistCompiledTaskSummarySchema, WorklistProjectionSchema, } from "./work-items.js";
 export { ActiveApprovalProjectionSchema, ApprovalCommandProjectionSchema, ApprovalDecisionKindSchema, ApprovalDecisionOptionProjectionSchema, ApprovalDecisionToneSchema, ApprovalFileChangeProjectionSchema, ApprovalPermissionsProjectionSchema, ApprovalRequestKindSchema, ApprovalRequestProjectionSchema, ApprovalResolutionOutcomeSchema, ApprovalResolutionProjectionSchema, DecideApprovalBodySchema, DecideApprovalDispositionSchema, DecideApprovalPayloadSchema, DecideApprovalResponseSchema, DecideApprovalResultSchema, } from "./approvals.js";
 export { ActiveClarificationProjectionSchema, ClarificationChangedEventPayloadSchema, ClarificationOwnerProjectionSchema, ClarificationRequestPayloadSchema, ClarificationRoundProjectionSchema, ClarificationRoundSummaryProjectionSchema, ClarificationSuccessorRefSchema, ClarificationThreadProjectionSchema, ContextRefSchema, GetClarificationRoundMessagesRequestSchema, GetClarificationRoundResponseSchema, GetClarificationThreadResponseSchema, HumanInteractionPayloadSchema, HumanRequestPayloadSchema, SendClarificationRoundMessageBodySchema, SendClarificationRoundMessageDispositionSchema, SendClarificationRoundMessagePayloadSchema, SendClarificationRoundMessageResponseSchema, SendClarificationRoundMessageResultSchema, SubmitClarificationRoundBodySchema, SubmitClarificationRoundDispositionSchema, SubmitClarificationRoundPayloadSchema, SubmitClarificationRoundResponseSchema, SubmitClarificationRoundResultSchema, } from "./clarifications.js";

package/node_modules/@tutti/shared/dist/schemas/api/index.js

@@ -5,7 +5,7 @@ export { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchema, Pr
 export { ProjectTimelineChangeStatusSchema, ProjectTimelineClarificationTraceSchema, ProjectTimelineDecisionSummarySchema, ProjectTimelineItemKindSchema, ProjectTimelineItemSchema, ProjectTimelineItemStatusSchema, ProjectTimelineResponseSchema, ProjectTimelineSourceSnippetSchema, ProjectTimelineTaskUpdateStateSchema, ProjectTimelineTraceCardSchema, ProjectTimelineTraceLinkSchema, ProjectTimelineTraceToneSchema, } from "./project-timeline.js";
 export { MAX_REFERENCE_STAGED_UPLOAD_BYTES, MAX_SKILL_ZIP_STAGED_UPLOAD_BYTES, MAX_STAGED_UPLOAD_BYTES, PresignedUploadPutSchema, ReferenceFileStartRelayUploadPayloadSchema, ReferenceStagedUploadReferenceProperties, RelayUploadProjectionSchema, RelayUploadPurposeSchema, Sha256DigestSchema, SkillZipStartRelayUploadPayloadSchema, SkillZipStagedUploadReferenceProperties, StagedUploadReferenceProperties, StagedUploadReferenceSchema, StartRelayUploadBodySchema, StartRelayUploadDispositionSchema, StartRelayUploadPayloadSchema, StartRelayUploadResponseSchema, StartRelayUploadResultSchema, maxStagedUploadBytesForPurpose, } from "./uploads.js";
 export { MarkReadBodySchema, MarkReadDispositionSchema, MarkReadPayloadSchema, MarkReadResponseSchema, MarkReadResultSchema, ReadStateScopeProjectionSchema, ReadStateScopeSchema, ReadStateSummaryProjectionSchema, } from "./read-state.js";
-export { GetMessagesRequestSchema, MessageAuthorSchema, MessageCreatedEventPayloadSchema, MessageKindSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, MessageRefsSchema, MessageScopeSchema, MessageWindowSchema, ReferenceFileCategorySchema, SendMainChatMessageBodySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResponseSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, WorklistCompileRefSchema, WorklistFeedbackItemSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackRefSchema, } from "./messages.js";
+export { GetMessagesRequestSchema, MessageAuthorSchema, MessageCreatedEventPayloadSchema, MessageKindSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, MessageRefsSchema, MessageScopeSchema, MessageWindowSchema, ReferenceFileCategorySchema, SendMainChatMessageBodySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResponseSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, TaskResultRefSchema, WorklistCompileRefSchema, WorklistFeedbackItemSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackRefSchema, } from "./messages.js";
 export { CheckSkipReasonCodeSchema, ExternalSideEffectSummaryProjectionSchema, GetRecoverySummariesRequestSchema, GetRecoverySummariesResponseSchema, GetRecoverySummaryResponseSchema, RecoverySummaryProjectionSchema, ResultAnchorSchema, RunLineageSchema, RunResultProjectionSchema, ScratchpadProjectionSchema, ScratchpadReceiptProjectionSchema, TaskContractProjectionSchema, TaskDetailProjectionSchema, TaskDetailResultProjectionSchema, TaskModuleProjectionSchema, TaskProjectionSchema, TaskRunResultsPageSchema, TaskStatusSchema, WorklistCompiledTaskSummarySchema, WorklistProjectionSchema, } from "./work-items.js";
 export { ActiveApprovalProjectionSchema, ApprovalCommandProjectionSchema, ApprovalDecisionKindSchema, ApprovalDecisionOptionProjectionSchema, ApprovalDecisionToneSchema, ApprovalFileChangeProjectionSchema, ApprovalPermissionsProjectionSchema, ApprovalRequestKindSchema, ApprovalRequestProjectionSchema, ApprovalResolutionOutcomeSchema, ApprovalResolutionProjectionSchema, DecideApprovalBodySchema, DecideApprovalDispositionSchema, DecideApprovalPayloadSchema, DecideApprovalResponseSchema, DecideApprovalResultSchema, } from "./approvals.js";
 export { ActiveClarificationProjectionSchema, ClarificationChangedEventPayloadSchema, ClarificationOwnerProjectionSchema, ClarificationRequestPayloadSchema, ClarificationRoundProjectionSchema, ClarificationRoundSummaryProjectionSchema, ClarificationSuccessorRefSchema, ClarificationThreadProjectionSchema, ContextRefSchema, GetClarificationRoundMessagesRequestSchema, GetClarificationRoundResponseSchema, GetClarificationThreadResponseSchema, HumanInteractionPayloadSchema, HumanRequestPayloadSchema, SendClarificationRoundMessageBodySchema, SendClarificationRoundMessageDispositionSchema, SendClarificationRoundMessagePayloadSchema, SendClarificationRoundMessageResponseSchema, SendClarificationRoundMessageResultSchema, SubmitClarificationRoundBodySchema, SubmitClarificationRoundDispositionSchema, SubmitClarificationRoundPayloadSchema, SubmitClarificationRoundResponseSchema, SubmitClarificationRoundResultSchema, } from "./clarifications.js";

package/node_modules/@tutti/shared/dist/schemas/api/messages.d.ts

@@ -89,6 +89,27 @@ export declare const WorklistFeedbackRefSchema: import("@sinclair/typebox").TObj
     }>>>;
     primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
+export declare const TaskResultRefSchema: import("@sinclair/typebox").TObject<{
+    kind: import("@sinclair/typebox").TLiteral<"task_result">;
+    status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+    title: import("@sinclair/typebox").TString;
+    task_id: import("@sinclair/typebox").TString;
+    task_title: import("@sinclair/typebox").TString;
+    result_key: import("@sinclair/typebox").TString;
+    summary: import("@sinclair/typebox").TString;
+    module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+        name: import("@sinclair/typebox").TString;
+        group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        size_bytes: import("@sinclair/typebox").TInteger;
+        media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
 export declare const WorklistCompileRefSchema: import("@sinclair/typebox").TObject<{
     kind: import("@sinclair/typebox").TLiteral<"worklist_compile">;
     workflow_ref: import("@sinclair/typebox").TString;
@@ -173,6 +194,27 @@ export declare const MessageRefsSchema: import("@sinclair/typebox").TObject<{
         }>>>;
         primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
+    task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        kind: import("@sinclair/typebox").TLiteral<"task_result">;
+        status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+        title: import("@sinclair/typebox").TString;
+        task_id: import("@sinclair/typebox").TString;
+        task_title: import("@sinclair/typebox").TString;
+        result_key: import("@sinclair/typebox").TString;
+        summary: import("@sinclair/typebox").TString;
+        module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            path: import("@sinclair/typebox").TString;
+            name: import("@sinclair/typebox").TString;
+            group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            size_bytes: import("@sinclair/typebox").TInteger;
+            media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>>;
+        error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
     artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
         title: import("@sinclair/typebox").TString;
@@ -269,6 +311,27 @@ export declare const MessageProjectionSchema: import("@sinclair/typebox").TObjec
             }>>>;
             primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         }>>;
+        task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            kind: import("@sinclair/typebox").TLiteral<"task_result">;
+            status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+            title: import("@sinclair/typebox").TString;
+            task_id: import("@sinclair/typebox").TString;
+            task_title: import("@sinclair/typebox").TString;
+            result_key: import("@sinclair/typebox").TString;
+            summary: import("@sinclair/typebox").TString;
+            module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                path: import("@sinclair/typebox").TString;
+                name: import("@sinclair/typebox").TString;
+                group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                size_bytes: import("@sinclair/typebox").TInteger;
+                media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>>;
+            error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
         artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
             kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
             title: import("@sinclair/typebox").TString;
@@ -389,6 +452,27 @@ export declare const SendMainChatMessageResultSchema: import("@sinclair/typebox"
                 }>>>;
                 primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
+            task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                kind: import("@sinclair/typebox").TLiteral<"task_result">;
+                status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+                title: import("@sinclair/typebox").TString;
+                task_id: import("@sinclair/typebox").TString;
+                task_title: import("@sinclair/typebox").TString;
+                result_key: import("@sinclair/typebox").TString;
+                summary: import("@sinclair/typebox").TString;
+                module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                    path: import("@sinclair/typebox").TString;
+                    name: import("@sinclair/typebox").TString;
+                    group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                    size_bytes: import("@sinclair/typebox").TInteger;
+                    media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                }>>>;
+                error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
             artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
                 title: import("@sinclair/typebox").TString;
@@ -506,6 +590,27 @@ export declare const MessageCreatedEventPayloadSchema: import("@sinclair/typebox
                 }>>>;
                 primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
+            task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                kind: import("@sinclair/typebox").TLiteral<"task_result">;
+                status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+                title: import("@sinclair/typebox").TString;
+                task_id: import("@sinclair/typebox").TString;
+                task_title: import("@sinclair/typebox").TString;
+                result_key: import("@sinclair/typebox").TString;
+                summary: import("@sinclair/typebox").TString;
+                module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                    path: import("@sinclair/typebox").TString;
+                    name: import("@sinclair/typebox").TString;
+                    group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                    size_bytes: import("@sinclair/typebox").TInteger;
+                    media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                }>>>;
+                error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
             artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
                 title: import("@sinclair/typebox").TString;

package/node_modules/@tutti/shared/dist/schemas/api/messages.js

@@ -92,6 +92,21 @@ export const WorklistFeedbackRefSchema = Type.Object({
     generated_files: Type.Optional(Type.Array(WorklistFeedbackGeneratedFileSchema)),
     primary_task_id: Type.Optional(TaskIdSchema),
 }, { additionalProperties: false });
+export const TaskResultRefSchema = Type.Object({
+    kind: Type.Literal("task_result"),
+    status: Type.Union([Type.Literal("completed"), Type.Literal("failed")]),
+    title: NonEmptyStringSchema,
+    task_id: TaskIdSchema,
+    task_title: NonEmptyStringSchema,
+    result_key: NonEmptyStringSchema,
+    summary: Type.String(),
+    module_name: Type.Optional(NonEmptyStringSchema),
+    latest_run_result_id: Type.Optional(RunResultIdSchema),
+    activity_ref: Type.Optional(ActivityRefSchema),
+    final_note: Type.Optional(Type.String()),
+    generated_files: Type.Optional(Type.Array(WorklistFeedbackGeneratedFileSchema)),
+    error_code: Type.Optional(NonEmptyStringSchema),
+}, { additionalProperties: false });
 export const WorklistCompileRefSchema = Type.Object({
     kind: Type.Literal("worklist_compile"),
     workflow_ref: WorkflowInvocationRefSchema,
@@ -116,6 +131,7 @@ export const MessageRefsSchema = Type.Object({
     reference_file: Type.Optional(MessageReferenceFileRefSchema),
     worklist_compile: Type.Optional(WorklistCompileRefSchema),
     worklist_feedback: Type.Optional(WorklistFeedbackRefSchema),
+    task_result: Type.Optional(TaskResultRefSchema),
     artifact_preview: Type.Optional(ArtifactPreviewRefSchema),
 }, { additionalProperties: false });
 export const MessageProjectionSchema = Type.Object({

package/node_modules/@tutti/shared/dist/schemas/api/types.d.ts

@@ -6,7 +6,7 @@ import type { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchem
 import type { ProjectTimelineItemKindSchema, ProjectTimelineItemSchema, ProjectTimelineItemStatusSchema, ProjectTimelineResponseSchema, ProjectTimelineTaskUpdateStateSchema, ProjectTimelineClarificationTraceSchema, ProjectTimelineTraceCardSchema, ProjectTimelineTraceLinkSchema } from "./project-timeline.js";
 import type { PresignedUploadPutSchema, RelayUploadProjectionSchema, RelayUploadPurposeSchema, Sha256DigestSchema, StagedUploadReferenceSchema, StartRelayUploadDispositionSchema, StartRelayUploadPayloadSchema, StartRelayUploadResultSchema } from "./uploads.js";
 import type { MarkReadDispositionSchema, MarkReadPayloadSchema, MarkReadResultSchema, ReadStateScopeProjectionSchema, ReadStateScopeSchema, ReadStateSummaryProjectionSchema } from "./read-state.js";
-import type { GetMessagesRequestSchema, MessageCreatedEventPayloadSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, ReferenceFileCategorySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, WorklistCompileRefSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackItemSchema, WorklistFeedbackRefSchema } from "./messages.js";
+import type { GetMessagesRequestSchema, MessageCreatedEventPayloadSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, ReferenceFileCategorySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResultSchema, ArtifactPreviewRefSchema, TaskResultRefSchema, WorklistCompileRefSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackItemSchema, WorklistFeedbackRefSchema } from "./messages.js";
 import type { CheckSkipReasonCodeSchema, ExternalSideEffectSummaryProjectionSchema, GetRecoverySummariesRequestSchema, GetRecoverySummaryResponseSchema, RecoverySummaryProjectionSchema, RunResultProjectionSchema, ScratchpadProjectionSchema, ScratchpadReceiptProjectionSchema, TaskContractProjectionSchema, TaskDetailProjectionSchema, TaskDetailResultProjectionSchema, TaskModuleProjectionSchema, TaskProjectionSchema, TaskStatusSchema, WorklistCompiledTaskSummarySchema, WorklistProjectionSchema } from "./work-items.js";
 import type { ActiveApprovalProjectionSchema, ApprovalCommandProjectionSchema, ApprovalDecisionKindSchema, ApprovalDecisionOptionProjectionSchema, ApprovalFileChangeProjectionSchema, ApprovalPermissionsProjectionSchema, ApprovalRequestKindSchema, ApprovalRequestProjectionSchema, ApprovalResolutionOutcomeSchema, ApprovalResolutionProjectionSchema, DecideApprovalDispositionSchema, DecideApprovalPayloadSchema, DecideApprovalResultSchema } from "./approvals.js";
 import type { ActiveClarificationProjectionSchema, ClarificationChangedEventPayloadSchema, ClarificationOwnerProjectionSchema, ClarificationRequestPayloadSchema, ClarificationRoundProjectionSchema, ClarificationRoundSummaryProjectionSchema, ClarificationSuccessorRefSchema, ClarificationThreadProjectionSchema, ContextRefSchema, GetClarificationRoundMessagesRequestSchema, GetClarificationRoundResponseSchema, GetClarificationThreadResponseSchema, HumanInteractionPayloadSchema, HumanRequestPayloadSchema, SendClarificationRoundMessageDispositionSchema, SendClarificationRoundMessagePayloadSchema, SendClarificationRoundMessageResultSchema, SubmitClarificationRoundDispositionSchema, SubmitClarificationRoundPayloadSchema, SubmitClarificationRoundResultSchema } from "./clarifications.js";
@@ -104,6 +104,7 @@ export type MessageReferenceFileRef = Static<typeof MessageReferenceFileRefSchem
 export type WorklistCompiledTaskSummary = Static<typeof WorklistCompiledTaskSummarySchema>;
 export type WorklistCompileRef = Static<typeof WorklistCompileRefSchema>;
 export type ArtifactPreviewRef = Static<typeof ArtifactPreviewRefSchema>;
+export type TaskResultRef = Static<typeof TaskResultRefSchema>;
 export type WorklistFeedbackItem = Static<typeof WorklistFeedbackItemSchema>;
 export type WorklistFeedbackGeneratedFile = Static<typeof WorklistFeedbackGeneratedFileSchema>;
 export type WorklistFeedbackRef = Static<typeof WorklistFeedbackRefSchema>;

package/node_modules/@tutti/shared/dist/schemas/api/viewer-reference.d.ts

@@ -467,6 +467,27 @@ export declare const UploadReferenceFileResultSchema: import("@sinclair/typebox"
                 }>>>;
                 primary_task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
+            task_result: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                kind: import("@sinclair/typebox").TLiteral<"task_result">;
+                status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"completed">, import("@sinclair/typebox").TLiteral<"failed">]>;
+                title: import("@sinclair/typebox").TString;
+                task_id: import("@sinclair/typebox").TString;
+                task_title: import("@sinclair/typebox").TString;
+                result_key: import("@sinclair/typebox").TString;
+                summary: import("@sinclair/typebox").TString;
+                module_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                latest_run_result_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                activity_ref: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                final_note: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                generated_files: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+                    path: import("@sinclair/typebox").TString;
+                    name: import("@sinclair/typebox").TString;
+                    group: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                    size_bytes: import("@sinclair/typebox").TInteger;
+                    media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                }>>>;
+                error_code: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
             artifact_preview: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 kind: import("@sinclair/typebox").TLiteral<"artifact_preview">;
                 title: import("@sinclair/typebox").TString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/prompts/prompt-flow-map.md

@@ -127,7 +127,7 @@ launch / join
 -> 可自纠 pipeline feedback 时在当前 Run 内部 retry
 -> promotion
 -> 如果 canonical Project Docs 被 promotion 修改，Project Brief 非阻塞尽力刷新
--> Worklist terminal feedback
+-> task result feedback
 -> 当前 Worklist 全部 done 后阶段性 context_sync
 -> Project Brief 尽力刷新
 -> 回写状态 / 文档 / 下一轮讨论

package/prompts/runs/README.md

@@ -10,7 +10,7 @@ Templates in this directory may describe task contracts, repo evidence, check ex
 `task-run.md` allows `needs_human` only for human requirement decisions, non-secret context, or risk confirmation. Unusable candidates, ordinary missing diffs, or repo/tooling errors that prevent implementation should be returned as `failed` so the Run does not open task-bound clarification incorrectly. If the task contract does not require repository file changes, the output can use `completed_no_repo_changes`; otherwise a completed implementation is expected to produce a candidate diff. If the candidate is complete but Codex self-validation commands are unavailable or blocked, the task-run output should still be `completed`; Tutti checks are the authoritative validation gate.
 Initial `task-run.md`, active `task-continuation.md`, and active pipeline `task-retry.md` receive only the compact task contract fields `title / goal / scope`; continuation adds the required `continuation` block, and pipeline self-correction retry adds the required `correction` block with only the previous failure summary, machine-generated reason code, correction guidance, and optional promotion failure summary. Provider-facing prompts do not receive task ids, task summaries, Run lineage, workflow anchors, changed paths, docs status, checks status, or the safety audit context entry.
 All three Run templates use a slim mutually exclusive structured output schema under `result`: exactly one of `completed.{summary,user_note_candidate}`, `completed_no_repo_changes.{summary,user_note_candidate}`, `needs_human.{title,summary,request}`, or `failed.summary`. The `summary` is a concise, human-readable result note for project members who may not inspect the code. Completed branches also require `user_note_candidate`, which is either a short user-facing final-card sentence or `null`; it must not repeat `summary` or include file paths. Checks, docs, promotion, changed paths, and other Tutti status stay in structured fields derived by the Run pipeline. They do not ask Codex to self-report docs status or changed paths; both come from Run pipeline Git diff and derived projection.
-Run templates describe `docs/reference/` as a user-visible file exchange area. Human uploads remain under `docs/reference/files/` and `docs/reference/images/`; `docs/reference/tutti/**` is for Tutti-generated files intended for direct member review in References, not temporary output, internal notes, logs, or canonical project documentation. Generated user-visible files must be written under `docs/reference/tutti/`, with `docs/reference/tutti/<meaningful-folder>/...` used when the folder name should be shown as a References UI group. Generated files under `docs/reference/tutti/` are discovered from promoted changed paths, rendered by References automatically, and may be listed in Worklist terminal feedback.
+Run templates describe `docs/reference/` as a user-visible file exchange area. Human uploads remain under `docs/reference/files/` and `docs/reference/images/`; `docs/reference/tutti/**` is for Tutti-generated files intended for direct member review in References, not temporary output, internal notes, logs, or canonical project documentation. Generated user-visible files must be written under `docs/reference/tutti/`, with `docs/reference/tutti/<meaningful-folder>/...` used when the folder name should be shown as a References UI group. Generated files under `docs/reference/tutti/` are discovered from promoted changed paths, rendered by References automatically, and may be listed in completed task result cards.
 Initial `task-run.md`, active `task-continuation.md`, and active pipeline `task-retry.md` also instruct Codex to write or update the single active `tutti.artifact.json` manifest only when the task creates or updates a member-viewable visual artifact. The manifest schema requires top-level `version: 1`; it must include a viewer-facing `artifact.title` and must set `artifact.network: true` when the preview loads remote browser resources. The manifest remains repo truth and is not reported through the structured output schema.
 Active task-bound follow-up still only starts continuation Runs from `Run.needs_human`. Pipeline self-correction retry happens before a terminal Run result is recorded and does not open clarification.
 Provider transient retry is separate from self-correction. If a retryable Codex app-server workspace-write failure occurs before usable structured output, Run pipeline may rerun the same prompt family once in a fresh run workspace: initial Runs stay on `task-run.md`, continuation Runs stay on `task-continuation.md`, and self-correction attempts stay on `task-retry.md`. This retry does not add `RunCorrectionContext` unless the failed attempt was already a self-correction attempt.

package/prompts/runs/task-continuation.md

@@ -64,7 +64,7 @@ Human-uploaded reference material is kept in the repository under `docs/referenc
 - Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
 - Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
 
-When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in completed task result cards. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation
 

package/prompts/runs/task-retry.md

@@ -69,7 +69,7 @@ Human-uploaded reference material is kept in the repository under `docs/referenc
 - Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
 - Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
 
-When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in completed task result cards. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation
 

package/prompts/runs/task-run.md

@@ -51,7 +51,7 @@ Human-uploaded reference material is kept in the repository under `docs/referenc
 - Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
 - Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
 
-When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in completed task result cards. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation