docs: define project scoping requirements and tasks (#5700)

Author: georgi

docs/project-scoping/prd.md

@@ -0,0 +1,157 @@
+# Project scoping PRD
+
+Status: agreed product scope, implementation pending.
+
+Companion: [Implementation tasks](tasks.md).
+
+## Problem
+
+A creator working on multiple deliverables needs to know which work belongs
+together and resume each deliverable without rebuilding their working context.
+NodeTool groups project documents, but its shared tab list and inconsistently
+scoped resource surfaces allow unrelated work to appear together. A project
+selector must control resource ownership and execution context as well as
+navigation.
+
+## Product outcome
+
+One project represents one deliverable, such as a film, campaign, or app.
+Selecting it brings back its working session and makes its resources the
+default context for browsing, creation, and agent work. Personal provides the
+same capabilities for experiments and work without a named deliverable.
+
+## Agreed decisions
+
+The decision IDs preserve the product discussion's references.
+
+| ID | Decision | Required behavior |
+| --- | --- | --- |
+| D1 | Project selection | A persistent selector sits above document tabs. It supports finding, switching, creating, and managing projects. Lists, search, pickers, and mentions use the selected project. |
+| D2 | Project session | Each project remembers its open tabs, order, active document, and selected chat. Switching preserves drafts. First opening shows the overview. Closing every tab leaves the project selected. |
+| D3 | Resource ownership | Documents, workflows, assets, entities, project files, chats, and generated outputs belong to a project. |
+| D4 | Creation and execution | New work inherits its originating project. Running generations and agents continue there after a switch. The selector shows background activity. |
+| D5 | Global resources | Account settings, credentials, installed models, and reusable templates remain global. Creating from a template produces project-owned work. |
+| D6 | Personal and migration | Personal is permanent and a project is always selected. A one-time migration assigns only unassigned resources to Personal. Existing project assignments remain intact. |
+| D7 | Project meaning | A named project represents one deliverable. Nested projects and client hierarchies are outside this release. |
+| D8 | Independent reuse | Copying into another project creates independent copies and includes referenced assets and entities. Edits never propagate between projects. |
+| D9 | Multiple conversations | Each project supports multiple chat threads. New threads receive project context and can work with its resources. |
+| D10 | Lifecycle | Finished projects can be archived. Deleting a project deletes its contents after confirmation. Personal cannot be deleted. |
+
+## Experience
+
+```text
+[ Project name v ]                              [ Account ]
+-----------------------------------------------------------
+Project navigation | This project's open document tabs
+                   | Active document
+                   | Project chat / inspector
+```
+
+### Switching and resuming
+
+The project name remains visible above the working area. Switching restores
+the destination's session rather than opening every document it owns. Returning
+to a project restores its drafts and focus. Reopening the application restores
+the selected project and its saved session, with Personal as the fallback.
+Tabs from other projects do not appear in the selected project's tab bar.
+
+Opening a link to a document in another project switches to its owning project
+before displaying it. A failed or superseded switch must not leave the header,
+tabs, and resource panels showing different projects.
+
+### Creating and finding work
+
+Creating documents, importing files, uploading media, generating outputs, and
+starting chats use the originating project's identity. Asset browsing, entity
+selection, mentions, resource search, and agent resource tools use that same
+scope. Scope must be enforced through resource operations, not just hidden
+rows in the interface or instructions in an agent prompt.
+
+Each supported resource type needs an explicit ownership path, including
+resource types missing from the existing project overview. Project files must
+use the workspace interface on both local and cloud storage.
+
+### Background work and conversations
+
+Switching projects does not cancel work. An upload, generation, or agent turn
+started in A continues to read and write A even while B is selected. Activity
+indicators identify the owning project and provide a route back to its work.
+
+Projects have multiple independent conversation histories. Project context
+does not mean inserting another thread's full conversation into a new thread.
+Selecting a thread cannot silently redirect its resource operations to the
+project most recently selected elsewhere.
+
+### Copying between projects
+
+An explicit copy action selects a destination project. The copy includes the
+referenced assets and entities needed to use the document independently.
+References in the copied content point to the destination copies. Multiple
+references to the same dependency within one copy operation reuse its copied
+identity. Source resources remain unchanged.
+
+The destination must remain usable after the source project is deleted.
+Missing dependencies or a failed copy must produce a clear failure rather
+than report a complete copy with broken references. Global prerequisites,
+such as installed models and credentials, remain global.
+
+### Migration and lifecycle
+
+On the first startup using this feature, create or resolve Personal for the
+resource owner and assign unassigned resources to it. Preserve IDs, content,
+references, and existing project assignments. Repeated startup or an
+interrupted migration must not duplicate Personal or move subsequently
+assigned resources. Existing tabs and conversation history remain reachable.
+
+Archive retains project contents and supports restoring the project. Archived
+projects remain discoverable through project management without crowding the
+normal selector. Delete confirmation identifies the project and explains that
+its contents will be removed. Deletion must not remove another project's
+copies or permit background operations to recreate deleted contents.
+
+## Release acceptance criteria
+
+| ID | Scenario | Pass condition |
+| --- | --- | --- |
+| AC1 | Switch A to B and back | A restores its tab order, active document, selected chat, and unsaved draft. Only A's tabs appear. |
+| AC2 | First open and close all tabs | A new project opens its overview. Closing all tabs leaves its project context active. |
+| AC3 | Browse and select resources | Lists, search, pickers, mentions, and agent queries return the selected project's resources plus explicitly global resource types. |
+| AC4 | Create through different entry points | UI, API, and agent creation assign the intended project consistently. Invalid project ownership is rejected. |
+| AC5 | Switch during work | A generation and agent turn started in A finish in A after switching to B. An upload started in B belongs to B. Activity links return to the correct project. |
+| AC6 | Multiple chats | A can create and reopen multiple threads. Switching to B shows B's threads and uses B's resources. Returning to A restores its selected thread. |
+| AC7 | Copy with dependencies | Copy a document with repeated asset and entity references into B, edit the copies, and delete A. B still works and its internal references resolve. |
+| AC8 | Migrate existing content | Assigned resources keep their projects. Unassigned resources enter Personal without losing content or references. Rerunning migration produces no additional changes. |
+| AC9 | Archive and delete | Archive preserves contents and can be reversed. Confirmed deletion removes the project's contents without affecting independent copies. Personal cannot be deleted. |
+| AC10 | Interrupted navigation and restart | Rapid switches, failed loads, direct document links, and application restart keep the selector, session, and resource scope consistent. |
+| AC11 | Complete coverage | A resource and entry-point inventory has no unhandled project-owned type or unscoped creation path. Local and cloud workspace behavior follow the same ownership rules. |
+
+## Scope boundaries
+
+| ID | Outside this release |
+| --- | --- |
+| N1 | Team membership, project sharing permissions, and collaboration roles. |
+| N2 | Nested projects, client hierarchies, and synchronized shared asset or entity libraries. |
+| N3 | A redesign of individual document editors or migration of global credentials and model installations into projects. |
+
+## Implementation questions
+
+These details need resolution during the tasks below. They do not change the
+agreed ownership model.
+
+| ID | Question | Resolve in |
+| --- | --- | --- |
+| Q10 | How should legacy references spanning assigned projects be preserved without breaking documents or introducing new shared ownership? | T1, T2 |
+| Q11 | Which linked document dependencies must also be copied, and how should unsupported external dependencies be reported? | T1, T8 |
+| Q12 | Should deletion wait for running work or explicitly cancel it, and how are retries prevented from writing afterward? | T9 |
+| Q13 | What existing move actions remain valid when moving a resource could break another document's references? | T1, T8 |
+
+## Starting points in the codebase
+
+These findings came from source inspection, not a live visual walkthrough.
+
+| ID | Finding | Source |
+| --- | --- | --- |
+| F1 | Project opening adds all project documents to a shared tab list and selects the overview. | [WorkspaceTabsStore](../../web/src/stores/WorkspaceTabsStore.ts), [useProjects](../../web/src/hooks/useProjects.ts) |
+| F2 | The entity library query searches assets without a project filter, while the overview has a project-specific entity section. | [useEntities](../../web/src/serverState/useEntities.ts), [ProjectEntitiesSection](../../web/src/components/projects/ProjectEntitiesSection.tsx) |
+| F3 | Assets carry a project field, but the inspected upload payload does not carry project context. | [AssetStore](../../web/src/stores/AssetStore.ts), [asset schema](../../packages/models/src/schema/assets.ts) |
+| F4 | The project document summary union omits workflows, and project metadata has one agent-thread pointer. | [project-summary](../../packages/models/src/project-summary.ts), [project schema](../../packages/models/src/schema/projects.ts) |

docs/project-scoping/tasks.md

@@ -0,0 +1,196 @@
+# Project scoping tasks
+
+Companion: [PRD](prd.md). All tasks are pending. Task IDs identify dependencies,
+not separate agent assignments.
+
+## Delivery order
+
+| Phase | Tasks | Outcome |
+| --- | --- | --- |
+| A1 | T1–T3 | Complete ownership, Personal migration, and operations bound to their originating project. |
+| A2 | T4–T7 | Project selection, isolated sessions, scoped resource surfaces, and multiple chats. |
+| A3 | T8–T10 | Independent copying, archive and deletion, and release verification. |
+
+## T1 — Inventory ownership and resource entry points
+
+- [ ] Enumerate document types, workflows, assets and folders, entities,
+      workspace files, threads, runs, and outputs. Record storage, ownership,
+      references, creation paths, list/search paths, and deletion behavior.
+- [ ] Cover web, Electron renderer, API, agent tools, background jobs, and
+      existing mobile consumers of affected contracts.
+- [ ] Classify each resource as project-owned or explicitly global using D3
+      and D5. Identify gaps beyond the existing project summary union.
+- [ ] Resolve legacy cross-project references and dependency-copy coverage
+      (Q10, Q11), and identify existing move behavior needing constraints (Q13).
+
+Depends on: none.
+
+Acceptance: a concrete file and entry-point inventory supports AC11. Every
+project-owned type has a planned owner, migration path, and resource boundary.
+
+## T2 — Complete project ownership and Personal migration
+
+- [ ] Add missing ownership fields and protocol contracts for the T1 inventory.
+      Keep backend schemas and supported database variants consistent.
+- [ ] Create or resolve one permanent Personal space per resource owner.
+- [ ] Implement an idempotent, restartable migration of unassigned resources.
+      Preserve existing assignments, IDs, content, and references.
+- [ ] Preserve access to existing tabs and threads after migration. Handle
+      malformed or dangling legacy membership explicitly without silently
+      moving valid assigned resources.
+- [ ] Add scoped model operations and project ownership validation. Preserve
+      compatibility of existing resource operations during rollout.
+
+Depends on: T1.
+
+Acceptance: AC8 and ownership portions of AC4/AC11. Verify empty accounts,
+mixed assigned/unassigned content, repeat startup, and interrupted migration.
+
+## T3 — Bind creation and execution to the originating project
+
+- [ ] Carry project identity through document creation, imports, uploads,
+      generation requests, runs, and agent sessions.
+- [ ] Capture scope when work starts. Persist enough context for delayed
+      completions and retries to use the original project.
+- [ ] Scope agent resource operations through backend contracts rather than
+      relying on prompts or the foreground tab.
+- [ ] Apply project file ownership through the workspace interface on local
+      and virtual storage. Keep global prerequisites outside project storage.
+- [ ] Expose project-attributed activity for the selector and navigation back
+      to running work.
+
+Depends on: T2.
+
+Acceptance: AC4, AC5, and AC11. Start work in A, switch to B before completion,
+and verify writes and resource reads still belong to A.
+
+## T4 — Persist separate project sessions
+
+- [ ] Store each project's open tabs, order, active document, and selected
+      chat independently from its full resource list.
+- [ ] Switch sessions without discarding drafts or reopening every document.
+- [ ] Define first-open overview, empty-tab state, restart restoration, and
+      Personal fallback.
+- [ ] Reconcile deleted or unavailable documents without changing another
+      project's saved session. Migrate existing persisted tab state.
+- [ ] Make rapid switches and failed loads leave one consistent active scope.
+
+Depends on: T2.
+
+Acceptance: AC1, AC2, and session portions of AC10. Verify switching with dirty
+editors and restart with multiple saved project sessions.
+
+## T5 — Put project selection above the tabs
+
+- [ ] Replace the tab-group scope control with a persistent top-level selector.
+      Add project search, creation, management access, and Personal.
+- [ ] Render only the selected project's tabs and project navigation.
+- [ ] Show activity from T3 and link it to the owning project's work.
+- [ ] Resolve direct document links to their owning project before opening.
+- [ ] Cover loading, failure, empty project, keyboard navigation, narrow
+      layouts, and Electron window controls using existing UI primitives.
+
+Depends on: T3, T4.
+
+Acceptance: D1, AC2, AC5, and AC10. Project identity remains visible and agrees
+with the tabs and content during every navigation transition.
+
+## T6 — Scope resource browsing and selection
+
+- [ ] Apply project scope to every T1 list, search, folder browser, asset
+      picker, entity picker, mention source, and project overview resource type.
+- [ ] Include project identity in query/cache and selection state where
+      required. Clear or restore panel state when switching projects.
+- [ ] Keep explicitly global resources available with clear scope.
+- [ ] Ensure entity membership and its backing/reference assets follow the
+      agreed ownership and migration rules.
+
+Depends on: T2, T3, T5.
+
+Acceptance: AC3 and AC11. Fixtures with identically named resources in A and B
+prove that browsing, selection, and mentions resolve the intended resource.
+
+## T7 — Support multiple chat threads per project
+
+- [ ] Replace the single-thread assumption with project-owned thread listing,
+      creation, selection, and history loading.
+- [ ] Preserve existing project conversations through migration.
+- [ ] Supply project context to new threads without merging thread histories.
+- [ ] Restore the selected chat through T4 and retain the thread's project
+      identity through background agent turns.
+
+Depends on: T3, T4, T5.
+
+Acceptance: AC6 and chat portions of AC1/AC5. Two threads in A and one in B
+retain their histories, selected state, and correct resource access.
+
+## T8 — Copy documents with independent dependencies
+
+- [ ] Implement destination selection and dependency discovery from the T1
+      reference inventory. Resolve Q11 and Q13 before finalizing behavior.
+- [ ] Copy required assets and entities, assign destination ownership, and
+      remap references. Handle repeated references and cycles without
+      duplicating the same dependency within one operation.
+- [ ] Preserve independent lifetimes even if immutable storage bytes are
+      internally deduplicated. Source deletion must not remove copied media.
+- [ ] Define failure and retry behavior so incomplete copies are not presented
+      as successful. Report unavailable or unsupported dependencies clearly.
+- [ ] Verify dependency traversal on a large resource graph.
+
+Depends on: T3, T6.
+
+Acceptance: AC7. Edit destination copies and delete the source project, then
+open and use the destination document with its assets and entities intact.
+
+## T9 — Archive and delete projects
+
+- [ ] Add archive and restore actions plus archived-project discovery.
+- [ ] Add confirmation naming the project and explaining content deletion.
+- [ ] Replace the existing return-to-unassigned deletion behavior with the
+      agreed content deletion behavior for the complete T1 inventory.
+- [ ] Protect Personal from deletion through both UI and backend operations.
+- [ ] Resolve Q12 and prevent active jobs, delayed responses, and retries from
+      writing into a deleted project.
+- [ ] Reconcile selected project, sessions, and caches after deletion. Preserve
+      independent copies and global resources.
+
+Depends on: T5, T7, T8.
+
+Acceptance: AC9 and deletion portion of AC7. Include deletion with active work,
+repeated deletion requests, and attempts to delete Personal.
+
+## T10 — Verify the complete project experience
+
+- [ ] Map every PRD acceptance criterion to a deterministic check or an
+      explicit UI walkthrough. Extend the existing relevant verification
+      surfaces and registry where needed.
+- [ ] Run the A/B scenario: restore A's tabs and chat, start work in A, switch
+      to B and upload, return to A, and verify session and output ownership.
+- [ ] Verify migration, dependency copying followed by source deletion,
+      archive/restore, direct links, rapid switching, and failed requests.
+- [ ] Check the final resource inventory for omitted types and entry points.
+- [ ] Perform web and Electron UI checks, including keyboard operation and
+      narrow layouts. Verify affected mobile contracts retain ownership
+      behavior without expanding this into a mobile navigation redesign.
+
+Depends on: T6, T7, T8, T9.
+
+Acceptance: AC1–AC11 have recorded evidence. Unresolved implementation
+questions are closed or explicitly returned for product decision before release.
+
+## Verification for implementation changes
+
+After each code change, run the repository's required checks:
+
+```bash
+npm run test:affected
+npm run typecheck
+npm run lint
+npm run dev:nodetool -- harness gate --base origin/main
+```
+
+Use meaningful regression fixtures for the boundaries each task changes.
+Prove any new validator can fail with a deliberately invalid fixture, and
+verify inventories contain actual entries. Follow the repository's additional
+requirements when a change crosses a dependency seam its affected-test
+selection cannot detect.