@xfey/tutti 0.1.97 → 0.1.98

package/dist/control-plane/index.js

@@ -1,7 +1,7 @@
-import { readActiveClarificationProjection, readActiveTaskCompileContext, markScratchpadRefreshSucceeded, readPendingTaskCompileSubmission, readTaskProjectionByActivityRef, readScratchpadSourceState, readWorklistProjection, } from "../collaboration-state/index.js";
+import { readActiveClarificationProjection, readActiveTaskCompileContext, markScratchpadRefreshSucceeded, readPendingTaskCompileSubmission, readTaskDetailProjection, readTaskProjectionByActivityRef, readScratchpadSourceState, readWorklistProjection, } from "../collaboration-state/index.js";
 import { ProcedureEngine } from "../procedure-engine/index.js";
 import { RunEngine } from "../run-engine/index.js";
-import { WorkspaceOpsError, readReferenceSummaryTargets } from "../workspace-ops/index.js";
+import { WorkspaceOpsError, isReferenceFilePath, readReferenceSummaryTargets, } from "../workspace-ops/index.js";
 import { publishProcedureTransition as publishProcedureTransitionEvent, publishRunResultRecorded as publishRunResultRecordedEvent, publishRunTransition as publishRunTransitionEvent, publishTaskRunStarted as publishTaskRunStartedEvent, } from "./event-publishers.js";
 import { startContextSyncAnalysisProcedure } from "./context-sync.js";
 import { refreshProjectBriefProjection, } from "./project-brief-refresh.js";
@@ -488,10 +488,22 @@ export class Phase5ControlPlane {
         this.pendingRunInputs.delete(activityRef);
         if (state.activity.status === "finished") {
             if (state.activity.task_id !== undefined) {
+                const taskId = state.activity.task_id;
+                const detail = readTaskDetailProjection(this.store.db, taskId);
+                const result = detail?.detail.result;
+                if (result?.result_kind === "finished" &&
+                    result.outcome === "completed" &&
+                    result.promotion?.status === "promoted") {
+                    for (const path of result.changed_paths ?? []) {
+                        if (isReferenceFilePath(path)) {
+                            this.pendingReferenceSummaryPaths.add(path);
+                        }
+                    }
+                }
                 emitTaskCompletedResultMessage({
                     store: this.store,
                     events: this.events,
-                    taskId: state.activity.task_id,
+                    taskId,
                     activityRef: state.activity.activity_ref,
                     ...(this.projectContext === undefined
                         ? {}

package/dist/control-plane/worklist-terminal-feedback.js

@@ -1,4 +1,4 @@
-import { readViewerFile, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "../workspace-ops/index.js";
+import { isReferenceFilePath, readViewerFile, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "../workspace-ops/index.js";
 import { createMainChatAgentMessage, hasMainChatTaskResultMessage, hasMainChatWorklistFeedbackMessage, readCompletedWorklistFeedbackTaskIds, readTaskDetailProjection, readWorklistProjection, } from "../collaboration-state/index.js";
 import { mainChatInvalidates } from "./invalidations.js";
 const BODY_ITEM_LIMIT = 12;
@@ -62,7 +62,7 @@ function generatedFileProjection(file) {
         name: file.name,
         size_bytes: file.size_bytes,
     };
-    const group = referenceTuttiGroupForPath(file.path);
+    const group = referenceFolderGroupForPath(file.path);
     if (group !== undefined) {
         projection.group = group;
     }
@@ -73,7 +73,7 @@ function generatedFileProjection(file) {
     return projection;
 }
 function readGeneratedFile(input) {
-    if (referenceFileSourceForPath(input.path) !== "tutti_output") {
+    if (!isReferenceFilePath(input.path)) {
         return null;
     }
     try {
@@ -100,7 +100,7 @@ function generatedFilesForCompletedEntries(input, entries) {
             continue;
         }
         for (const path of entry.detail?.detail.result.changed_paths ?? []) {
-            if (referenceFileSourceForPath(path) === "tutti_output") {
+            if (isReferenceFilePath(path)) {
                 paths.add(path);
             }
         }

package/dist/server-shell/http/routes/agent-context-references.js

@@ -1,4 +1,4 @@
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, WorkspaceOpsError, readReferenceSummaryIndex, readViewerFile, readViewerTree, referenceFileCategoryForPath, referenceMediaTypeForPath, referenceSummaryProjectionForEntry, } from "../../../workspace-ops/index.js";
+import { REFERENCE_INDEX_PATH, WorkspaceOpsError, readReferenceFileEntries, readReferenceSummaryIndex, readViewerFile, referenceFileCategoryForPath, referenceMediaTypeForPath, referenceSummaryProjectionForEntry, } from "../../../workspace-ops/index.js";
 import { AgentContextBadRequestError } from "./agent-context-errors.js";
 function requireWorkspaceRoot(options) {
     if (options.workspaceOps === undefined) {
@@ -46,14 +46,11 @@ function unavailableReasonForContent(content) {
 }
 function referenceEntries(options) {
     const workspaceRoot = requireWorkspaceRoot(options);
-    let tree;
     try {
-        tree = readViewerTree({
-            workspaceRoot,
-            path: REFERENCE_DIRECTORY_PATH,
-            depth: 2,
-            ...(options.now === undefined ? {} : { now: options.now }),
-        });
+        return readReferenceFileEntries({ workspaceRoot })
+            .filter((entry) => entry.path !== REFERENCE_INDEX_PATH)
+            .filter((entry) => referenceFileCategoryForPath(entry.path) !== undefined)
+            .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
     }
     catch (error) {
         if (error instanceof WorkspaceOpsError && error.code === "not_found") {
@@ -61,11 +58,6 @@ function referenceEntries(options) {
         }
         throw error;
     }
-    return tree.items
-        .filter((entry) => entry.kind === "file")
-        .filter((entry) => entry.path !== REFERENCE_INDEX_PATH)
-        .filter((entry) => referenceFileCategoryForPath(entry.path) !== undefined)
-        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
 }
 function canReadReferenceText(options, path) {
     try {
@@ -76,7 +68,9 @@ function canReadReferenceText(options, path) {
             ...(options.now === undefined ? {} : { now: options.now }),
         });
         const reason = unavailableReasonForContent(file.content);
-        return reason === undefined ? { can_read_text: true } : { can_read_text: false, blocked_reason: reason };
+        return reason === undefined
+            ? { can_read_text: true }
+            : { can_read_text: false, blocked_reason: reason };
     }
     catch {
         return { can_read_text: false, blocked_reason: "restricted_path" };

package/dist/server-shell/http/routes/project-api/openapi-viewer-routes.d.ts

@@ -283,14 +283,12 @@ export declare const HOST_PROJECT_VIEWER_OPENAPI_ROUTES: ({
                     index_path: import("@sinclair/typebox").TLiteral<"docs/reference/README.md">;
                     files_path: import("@sinclair/typebox").TLiteral<"docs/reference/files">;
                     images_path: import("@sinclair/typebox").TLiteral<"docs/reference/images">;
-                    tutti_path: import("@sinclair/typebox").TLiteral<"docs/reference/tutti">;
                     index_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"missing">, import("@sinclair/typebox").TLiteral<"unreadable">]>;
                     index_unreadable_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"restricted_path">, import("@sinclair/typebox").TLiteral<"secret_like">, import("@sinclair/typebox").TLiteral<"binary">, import("@sinclair/typebox").TLiteral<"unsupported_encoding">, import("@sinclair/typebox").TLiteral<"too_large">]>>;
                 }>;
                 items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
                     path: import("@sinclair/typebox").TString;
                     name: import("@sinclair/typebox").TString;
-                    source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
                     category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
                     size_bytes: import("@sinclair/typebox").TInteger;
                     media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/dist/server-shell/http/routes/project-api/reference-files.js

@@ -1,4 +1,4 @@
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, VIEWER_HARD_READ_LIMIT_BYTES, WorkspaceOpsError, readViewerFile, readViewerSnapshot, readViewerTree, readReferenceSummaryIndex, referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceSummaryProjectionForEntry, } from "../../../../workspace-ops/index.js";
+import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_HARD_READ_LIMIT_BYTES, WorkspaceOpsError, readReferenceFileEntries, readReferenceSummaryIndex, readViewerFile, readViewerSnapshot, referenceFileCategoryForPath, referenceMediaTypeForPath, referenceSummaryProjectionForEntry, } from "../../../../workspace-ops/index.js";
 import { paginateViewerItems, viewerPageLimit } from "./viewer-projections.js";
 function unreadableReasonForReferenceContent(content) {
     if (content.kind === "text") {
@@ -34,7 +34,6 @@ export function toReferenceFileProjection(options) {
         path: options.entry.path,
         name: options.entry.name,
         category,
-        source: referenceFileSourceForPath(options.entry.path) ?? "human_upload",
         size_bytes: options.entry.size_bytes ?? 0,
         text_read: referenceTextReadProjection(options.workspaceRoot, options.entry, options.now),
         summary: referenceSummaryProjectionForEntry({
@@ -65,7 +64,6 @@ function referenceDirectoryProjection(options) {
             index_path: REFERENCE_INDEX_PATH,
             files_path: REFERENCE_FILES_DIRECTORY_PATH,
             images_path: REFERENCE_IMAGES_DIRECTORY_PATH,
-            tutti_path: REFERENCE_TUTTI_DIRECTORY_PATH,
             index_status: "missing",
         };
     }
@@ -82,7 +80,6 @@ function referenceDirectoryProjection(options) {
                 index_path: REFERENCE_INDEX_PATH,
                 files_path: REFERENCE_FILES_DIRECTORY_PATH,
                 images_path: REFERENCE_IMAGES_DIRECTORY_PATH,
-                tutti_path: REFERENCE_TUTTI_DIRECTORY_PATH,
                 index_status: "available",
             };
         }
@@ -92,7 +89,6 @@ function referenceDirectoryProjection(options) {
             index_path: REFERENCE_INDEX_PATH,
             files_path: REFERENCE_FILES_DIRECTORY_PATH,
             images_path: REFERENCE_IMAGES_DIRECTORY_PATH,
-            tutti_path: REFERENCE_TUTTI_DIRECTORY_PATH,
             index_status: "unreadable",
             index_unreadable_reason: file.content.reason,
         };
@@ -105,7 +101,6 @@ function referenceDirectoryProjection(options) {
                 index_path: REFERENCE_INDEX_PATH,
                 files_path: REFERENCE_FILES_DIRECTORY_PATH,
                 images_path: REFERENCE_IMAGES_DIRECTORY_PATH,
-                tutti_path: REFERENCE_TUTTI_DIRECTORY_PATH,
                 index_status: "missing",
             };
         }
@@ -119,14 +114,9 @@ export function readReferenceFilesResponse(options, query) {
         workspaceRoot,
         ...(now === undefined ? {} : { now }),
     });
-    let tree;
+    let entries;
     try {
-        tree = readViewerTree({
-            workspaceRoot,
-            path: REFERENCE_DIRECTORY_PATH,
-            depth: 3,
-            ...(now === undefined ? {} : { now }),
-        });
+        entries = readReferenceFileEntries({ workspaceRoot });
     }
     catch (error) {
         if (error instanceof WorkspaceOpsError && error.code === "not_found") {
@@ -148,11 +138,10 @@ export function readReferenceFilesResponse(options, query) {
     }
     const includeIndex = query.include_index ?? false;
     const summaryIndex = readReferenceSummaryIndex({ workspaceRoot });
-    const referenceItems = tree.items
-        .filter((entry) => entry.kind === "file")
+    const referenceItems = entries
         .filter((entry) => includeIndex || entry.path !== REFERENCE_INDEX_PATH)
         .filter((entry) => entry.path === REFERENCE_INDEX_PATH ||
-        referenceFileSourceForPath(entry.path) !== undefined)
+        referenceFileCategoryForPath(entry.path) !== undefined)
         .sort((left, right) => {
         const leftCategory = referenceFileCategoryForPath(left.path) ?? "file";
         const rightCategory = referenceFileCategoryForPath(right.path) ?? "file";
@@ -202,7 +191,7 @@ export function referenceFileMessageRef(file) {
     const ref = {
         path: file.path,
         name: file.name,
-        source: file.source,
+        source: "human_upload",
         category: file.category,
         size_bytes: file.size_bytes,
         text_read: file.text_read,

package/dist/workspace-ops/constants.d.ts

@@ -5,7 +5,6 @@ export declare const VIEWER_HARD_READ_LIMIT_BYTES: number;
 export declare const REFERENCE_DIRECTORY_PATH: "docs/reference";
 export declare const REFERENCE_FILES_DIRECTORY_PATH: "docs/reference/files";
 export declare const REFERENCE_IMAGES_DIRECTORY_PATH: "docs/reference/images";
-export declare const REFERENCE_TUTTI_DIRECTORY_PATH: "docs/reference/tutti";
 export declare const REFERENCE_INDEX_PATH: "docs/reference/README.md";
 export declare const MAX_REFERENCE_UPLOAD_BYTES: number;
 export declare const VIEWER_ASSET_READ_LIMIT_BYTES: number;

package/dist/workspace-ops/constants.js

@@ -5,7 +5,6 @@ export const VIEWER_HARD_READ_LIMIT_BYTES = 5 * 1024 * 1024;
 export const REFERENCE_DIRECTORY_PATH = "docs/reference";
 export const REFERENCE_FILES_DIRECTORY_PATH = "docs/reference/files";
 export const REFERENCE_IMAGES_DIRECTORY_PATH = "docs/reference/images";
-export const REFERENCE_TUTTI_DIRECTORY_PATH = "docs/reference/tutti";
 export const REFERENCE_INDEX_PATH = "docs/reference/README.md";
 export const MAX_REFERENCE_UPLOAD_BYTES = 10 * 1024 * 1024;
 export const VIEWER_ASSET_READ_LIMIT_BYTES = MAX_REFERENCE_UPLOAD_BYTES;

package/dist/workspace-ops/index.d.ts

@@ -1,10 +1,11 @@
-export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
+export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
 export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
 export { uploadReferenceFile } from "./reference-files.js";
-export { referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "./reference-metadata.js";
+export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
+export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 export type { WorkspaceOpsErrorCode } from "./errors.js";

package/dist/workspace-ops/index.js

@@ -1,10 +1,11 @@
-export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
+export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
 export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
 export { uploadReferenceFile } from "./reference-files.js";
-export { referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "./reference-metadata.js";
+export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
+export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 //# sourceMappingURL=index.js.map

package/dist/workspace-ops/project-doc-templates.js

@@ -129,7 +129,7 @@ ${asBulletList([
                 ...repoHints.directories.map((directory) => `Top-level directory: \`${directory}/\``),
                 ...repoHints.root_files.map((file) => `Root file: \`${file}\``),
             ], "Repository structure is pending context sync.")}
-- Human-uploaded reference materials, when present, live under \`docs/reference/\`.
+- Shared reference materials maintained by project members and Tutti, when present, live under \`docs/reference/\`.
 
 ## Naming Conventions
 

package/dist/workspace-ops/reference-files.js

@@ -110,7 +110,7 @@ function appendReferenceIndexEntry(options) {
         ? [
             "# Reference Files",
             "",
-            "Human-uploaded project reference files.",
+            "Shared project reference files maintained by project members and Tutti.",
             "",
             "## Files",
             "",
@@ -185,7 +185,8 @@ export function uploadReferenceFile(options) {
         paths: [REFERENCE_INDEX_PATH, repoPath],
         message: `Add reference file: ${safeName}`,
     });
-    const resolvedCommitOid = commitOid ?? readViewerFile({ workspaceRoot: options.workspaceRoot, path: repoPath }).snapshot.head.oid;
+    const resolvedCommitOid = commitOid ??
+        readViewerFile({ workspaceRoot: options.workspaceRoot, path: repoPath }).snapshot.head.oid;
     const file = readViewerFile({
         workspaceRoot: options.workspaceRoot,
         path: repoPath,

package/dist/workspace-ops/reference-metadata.d.ts

@@ -9,7 +9,7 @@ export declare function classifyReferenceUpload(options: {
     directoryPath: string;
 };
 export declare function referenceFileCategoryForPath(path: string): ReferenceFileCategory | undefined;
-export declare function referenceFileSourceForPath(path: string): "human_upload" | "tutti_output" | undefined;
-export declare function referenceTuttiGroupForPath(path: string): string | undefined;
+export declare function isReferenceFilePath(path: string): boolean;
+export declare function referenceFolderGroupForPath(path: string): string | undefined;
 export declare function referenceMediaTypeForPath(path: string): string | undefined;
 //# sourceMappingURL=reference-metadata.d.ts.map

package/dist/workspace-ops/reference-metadata.js

@@ -1,5 +1,5 @@
-import { extname, posix } from "node:path";
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, } from "./constants.js";
+import { extname } from "node:path";
+import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
 const REFERENCE_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
 const REFERENCE_IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
 function normalizeMediaType(mediaType) {
@@ -54,33 +54,19 @@ export function referenceFileCategoryForPath(path) {
     if (path.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`)) {
         return "image";
     }
-    if (path.startsWith(`${REFERENCE_FILES_DIRECTORY_PATH}/`)) {
-        return "file";
-    }
-    if (path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
-        return "file";
-    }
-    if (posix.dirname(path) === REFERENCE_DIRECTORY_PATH && path !== REFERENCE_INDEX_PATH) {
+    if (isReferenceFilePath(path)) {
         return "file";
     }
     return undefined;
 }
-export function referenceFileSourceForPath(path) {
-    if (path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
-        return "tutti_output";
-    }
-    if (path.startsWith(`${REFERENCE_FILES_DIRECTORY_PATH}/`) ||
-        path.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`) ||
-        (posix.dirname(path) === REFERENCE_DIRECTORY_PATH && path !== REFERENCE_INDEX_PATH)) {
-        return "human_upload";
-    }
-    return undefined;
+export function isReferenceFilePath(path) {
+    return path !== REFERENCE_INDEX_PATH && path.startsWith(`${REFERENCE_DIRECTORY_PATH}/`);
 }
-export function referenceTuttiGroupForPath(path) {
-    if (!path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
+export function referenceFolderGroupForPath(path) {
+    if (!isReferenceFilePath(path)) {
         return undefined;
     }
-    const rest = path.slice(REFERENCE_TUTTI_DIRECTORY_PATH.length + 1);
+    const rest = path.slice(REFERENCE_DIRECTORY_PATH.length + 1);
     const [first, second] = rest.split("/");
     if (first === undefined || first.length === 0 || second === undefined) {
         return undefined;

package/dist/workspace-ops/reference-summaries.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { redactText } from "@tutti/shared/utils";
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+import { REFERENCE_INDEX_PATH } from "./constants.js";
 import { referenceFileCategoryForPath, referenceMediaTypeForPath } from "./reference-metadata.js";
+import { readReferenceFileEntries } from "./reference-tree.js";
 import { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
-import { readViewerTree } from "./viewer.js";
 const SUMMARY_SECTION_HEADING = "## Summaries";
 const SUMMARY_BLOCK_START = "<!-- tutti-reference-summaries:v1";
 const SUMMARY_BLOCK_END = "-->";
@@ -115,7 +115,7 @@ function readReferenceIndexContent(workspaceRoot) {
         return [
             "# Reference Files",
             "",
-            "Human-uploaded project reference files.",
+            "Shared project reference files maintained by project members and Tutti.",
             "",
             "## Files",
             "",
@@ -138,8 +138,7 @@ export function referenceSummaryProjectionForEntry(options) {
         ...(record.source_blob_oid === undefined ? {} : { source_blob_oid: record.source_blob_oid }),
         ...(record.read_paths === undefined ? {} : { read_paths: record.read_paths }),
     };
-    if (options.entry.blob_oid !== undefined &&
-        record.source_blob_oid !== options.entry.blob_oid) {
+    if (options.entry.blob_oid !== undefined && record.source_blob_oid !== options.entry.blob_oid) {
         return {
             status: "stale",
             ...base,
@@ -165,14 +164,8 @@ export function referenceSummaryProjectionForEntry(options) {
         ...(record.summary === undefined ? {} : { text: record.summary }),
     };
 }
-function readReferenceFileEntries(options) {
-    const tree = readViewerTree({
-        workspaceRoot: options.workspaceRoot,
-        path: REFERENCE_DIRECTORY_PATH,
-        depth: 2,
-        ...(options.now === undefined ? {} : { now: options.now }),
-    });
-    return tree.items
+function readSummaryFileEntries(options) {
+    return readReferenceFileEntries({ workspaceRoot: options.workspaceRoot })
         .filter((entry) => entry.kind === "file")
         .filter((entry) => referenceFileCategoryForPath(entry.path) !== undefined)
         .filter((entry) => entry.blob_oid !== undefined && entry.size_bytes !== undefined)
@@ -181,7 +174,7 @@ function readReferenceFileEntries(options) {
 export function readReferenceSummaryEntries(options) {
     const summaries = readReferenceSummaryIndex({ workspaceRoot: options.workspaceRoot });
     const requested = options.paths === undefined ? undefined : new Set(options.paths);
-    return readReferenceFileEntries(options)
+    return readSummaryFileEntries(options)
         .filter((entry) => requested === undefined || requested.has(entry.path))
         .map((entry) => {
         const category = referenceFileCategoryForPath(entry.path) ?? "file";
@@ -239,7 +232,9 @@ function renderSummaryRecord(record) {
     return rendered;
 }
 function renderSummariesSection(records) {
-    const items = records.map(renderSummaryRecord).sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+    const items = records
+        .map(renderSummaryRecord)
+        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
     const json = JSON.stringify({ items }, null, 2);
     const lines = [
         SUMMARY_SECTION_HEADING,
@@ -277,9 +272,8 @@ export function updateReferenceSummaries(options) {
         }
         existing.set(summary.path, rendered);
     }
-    const currentPaths = new Set(readReferenceFileEntries({
+    const currentPaths = new Set(readSummaryFileEntries({
         workspaceRoot: options.workspaceRoot,
-        ...(options.now === undefined ? {} : { now: options.now }),
     }).map((entry) => entry.path));
     const records = [...existing.values()].filter((record) => currentPaths.has(record.path));
     const nextContent = `${removeSummarySection(existingContent)}\n\n${renderSummariesSection(records)}\n`;

package/dist/workspace-ops/reference-tree.d.ts

@@ -0,0 +1,11 @@
+import type { ViewerTreeEntry } from "./types.js";
+/**
+ * Enumerate every committed regular file in the shared Reference directory.
+ * The generic Repo Viewer intentionally keeps its bounded depth contract; this
+ * Reference-specific reader is the single recursive source for the API,
+ * summaries, and agent context.
+ */
+export declare function readReferenceFileEntries(options: {
+    workspaceRoot: string;
+}): ViewerTreeEntry[];
+//# sourceMappingURL=reference-tree.d.ts.map

package/dist/workspace-ops/reference-tree.js

@@ -0,0 +1,34 @@
+import { posix } from "node:path";
+import { REFERENCE_DIRECTORY_PATH } from "./constants.js";
+import { WorkspaceOpsError } from "./errors.js";
+import { entryKind, lsPath, lsTreeRecursive } from "./viewer-git.js";
+import { isPathAllowedForProjection } from "./viewer-paths.js";
+import { createViewerTreeEntry } from "./viewer-tree.js";
+/**
+ * Enumerate every committed regular file in the shared Reference directory.
+ * The generic Repo Viewer intentionally keeps its bounded depth contract; this
+ * Reference-specific reader is the single recursive source for the API,
+ * summaries, and agent context.
+ */
+export function readReferenceFileEntries(options) {
+    const root = lsPath(options.workspaceRoot, REFERENCE_DIRECTORY_PATH);
+    if (root === null) {
+        throw new WorkspaceOpsError("not_found", "Reference directory was not found");
+    }
+    if (entryKind(root) !== "directory") {
+        throw new WorkspaceOpsError("validation_failed", "Reference path is not a directory");
+    }
+    return lsTreeRecursive(options.workspaceRoot, REFERENCE_DIRECTORY_PATH)
+        .filter((entry) => entryKind(entry) === "file")
+        .filter((entry) => isPathAllowedForProjection(entry.path))
+        .map((entry) => {
+        const relativePath = entry.path.slice(REFERENCE_DIRECTORY_PATH.length + 1);
+        return createViewerTreeEntry(entry, {
+            path: entry.path,
+            parentPath: posix.dirname(entry.path),
+            depth: relativePath.split("/").length,
+        });
+    })
+        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+}
+//# sourceMappingURL=reference-tree.js.map

package/dist/workspace-ops/viewer-git.d.ts

@@ -9,6 +9,7 @@ export type RawTreeEntry = {
 export declare function readViewerSnapshot(options: WorkspaceViewerOptions): ViewerRepoSnapshot;
 export declare function lsPath(workspaceRoot: string, normalizedPath: string): RawTreeEntry | null;
 export declare function lsDirectoryChildren(workspaceRoot: string, normalizedPath: string): RawTreeEntry[];
+export declare function lsTreeRecursive(workspaceRoot: string, normalizedPath: string): RawTreeEntry[];
 export declare function entryKind(entry: RawTreeEntry): ViewerEntryKind;
 export declare function requireFileEntry(options: {
     workspaceRoot: string;

package/dist/workspace-ops/viewer-git.js

@@ -76,6 +76,17 @@ export function lsDirectoryChildren(workspaceRoot, normalizedPath) {
         : `${WORKSPACE_OPS_MAINLINE_BRANCH}:${normalizedPath}`;
     return lsTree(workspaceRoot, ["ls-tree", "-z", "-l", treeish]);
 }
+export function lsTreeRecursive(workspaceRoot, normalizedPath) {
+    return lsTree(workspaceRoot, [
+        "ls-tree",
+        "-r",
+        "-z",
+        "-l",
+        WORKSPACE_OPS_MAINLINE_BRANCH,
+        "--",
+        normalizedPath,
+    ]);
+}
 export function entryKind(entry) {
     if (entry.mode === "040000" || entry.type === "tree") {
         return "directory";

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

@@ -250,7 +250,6 @@ export declare const ReferenceDirectoryProjectionSchema: import("@sinclair/typeb
     index_path: import("@sinclair/typebox").TLiteral<"docs/reference/README.md">;
     files_path: import("@sinclair/typebox").TLiteral<"docs/reference/files">;
     images_path: import("@sinclair/typebox").TLiteral<"docs/reference/images">;
-    tutti_path: import("@sinclair/typebox").TLiteral<"docs/reference/tutti">;
     index_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"missing">, import("@sinclair/typebox").TLiteral<"unreadable">]>;
     index_unreadable_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"restricted_path">, import("@sinclair/typebox").TLiteral<"secret_like">, import("@sinclair/typebox").TLiteral<"binary">, import("@sinclair/typebox").TLiteral<"unsupported_encoding">, import("@sinclair/typebox").TLiteral<"too_large">]>>;
 }>;
@@ -266,7 +265,6 @@ export declare const ReferenceSummaryProjectionSchema: import("@sinclair/typebox
 export declare const ReferenceFileProjectionSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     name: import("@sinclair/typebox").TString;
-    source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
     category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
     size_bytes: import("@sinclair/typebox").TInteger;
     media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -308,14 +306,12 @@ export declare const GetReferenceFilesResponseSchema: import("@sinclair/typebox"
         index_path: import("@sinclair/typebox").TLiteral<"docs/reference/README.md">;
         files_path: import("@sinclair/typebox").TLiteral<"docs/reference/files">;
         images_path: import("@sinclair/typebox").TLiteral<"docs/reference/images">;
-        tutti_path: import("@sinclair/typebox").TLiteral<"docs/reference/tutti">;
         index_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"missing">, import("@sinclair/typebox").TLiteral<"unreadable">]>;
         index_unreadable_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"restricted_path">, import("@sinclair/typebox").TLiteral<"secret_like">, import("@sinclair/typebox").TLiteral<"binary">, import("@sinclair/typebox").TLiteral<"unsupported_encoding">, import("@sinclair/typebox").TLiteral<"too_large">]>>;
     }>;
     items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
         name: import("@sinclair/typebox").TString;
-        source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
         category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
         size_bytes: import("@sinclair/typebox").TInteger;
         media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -359,7 +355,6 @@ export declare const UploadReferenceFileResultSchema: import("@sinclair/typebox"
     file: import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
         name: import("@sinclair/typebox").TString;
-        source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
         category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
         size_bytes: import("@sinclair/typebox").TInteger;
         media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

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

@@ -164,7 +164,6 @@ export const ReferenceDirectoryProjectionSchema = Type.Object({
     index_path: Type.Literal("docs/reference/README.md"),
     files_path: Type.Literal("docs/reference/files"),
     images_path: Type.Literal("docs/reference/images"),
-    tutti_path: Type.Literal("docs/reference/tutti"),
     index_status: Type.Union([
         Type.Literal("available"),
         Type.Literal("missing"),
@@ -196,7 +195,6 @@ export const ReferenceSummaryProjectionSchema = Type.Object({
 export const ReferenceFileProjectionSchema = Type.Object({
     path: ViewerPathSchema,
     name: NonEmptyStringSchema,
-    source: Type.Union([Type.Literal("human_upload"), Type.Literal("tutti_output")]),
     category: ReferenceFileCategorySchema,
     size_bytes: Type.Integer({ minimum: 0 }),
     media_type: Type.Optional(NonEmptyStringSchema),

package/package.json

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

package/prompts/procedures/context-sync.md

@@ -16,9 +16,9 @@ Use repository inspection and attached skills only when useful:
 
 - Use `read-project-docs` for existing project documents and availability.
 - Use `read-worklist` when repo state or completed formal tasks can explain the current implementation stage. Do not turn task results into a changelog.
-- Use `read-references` only when a human-uploaded reference file's actual content matters.
+- Use `read-references` only when a file in the shared project Reference space actually matters.
 
-Reference upload events, file names, media types, and paths do not prove file contents. Read the relevant file before relying on it.
+Reference creation events, file names, media types, paths, and summaries do not prove file contents. Read the relevant file before relying on it.
 
 # Documentation Scope
 
@@ -62,5 +62,5 @@ Return only JSON matching this schema:
 If no concrete documentation update is needed, return an empty `updates` array:
 
 ```json
-{"summary":"Checked current docs against repository facts; no updates needed.","updates":[]}
+{ "summary": "Checked current docs against repository facts; no updates needed.", "updates": [] }
 ```

package/prompts/procedures/reference-file-summary.md

@@ -6,7 +6,7 @@ model_path: codex.app_server.read_only
 
 # Role
 
-You summarize one human-uploaded Tutti reference file.
+You summarize one file from Tutti's shared project Reference space.
 
 # Runtime
 

package/prompts/procedures/task-compile.md

@@ -36,9 +36,9 @@ You compile Tutti's Scratchpad into an append-only Worklist proposal for post-ba
 Tutti can expose direct user-viewable outputs through two repo-backed surfaces when a task result is meant for project members to inspect:
 
 - a single active visual artifact, declared by `tutti.artifact.json`, for previewable pages, apps, dashboards, or similar interactive outputs;
-- generated files under `docs/reference/tutti/**`, for reviewable files such as reports, notes, specs, exports, or similar outputs.
+- generated files in the shared `docs/reference/**` space, directly at the root or under a meaningful semantic subfolder, for reviewable files such as reports, notes, specs, exports, or similar outputs.
 
-Treat these as delivery surfaces, not as task subjects by themselves. Human-uploaded references still live under `docs/reference/files/` or `docs/reference/images/`, and stable project facts still belong in the relevant project docs or README-style files.
+Treat these as delivery surfaces, not as task subjects by themselves. Browser uploads continue to enter the Host-managed `docs/reference/files/` or `docs/reference/images/` partitions, `docs/reference/README.md` remains Host-owned, and stable project facts still belong in the relevant project docs or README-style files.
 
 When the Scratchpad clearly asks for one of these direct deliverables, include a concise task `scope` item naming the expected surface. If a completion card should call out the result or generated file name, the scope may also mention `user_note_candidate`. Do not add artifact or generated-reference outputs solely to create feedback for ordinary implementation tasks.