From 41aeefc1828b06576b168373cdf274ded734cb0a Mon Sep 17 00:00:00 2001 From: mirivlad Date: Tue, 14 Jul 2026 23:57:50 +0800 Subject: [PATCH] docs: describe Deals as the user-facing unit --- README.md | 30 ++++++------- README.ru.md | 6 +-- docs/PLUGIN_RUNTIME.md | 88 +++++++++++++++++++------------------ docs/WORKSPACE_TEMPLATES.md | 22 +++++----- 4 files changed, 74 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 1a6f143..02ae20e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ### Keep the context of your work together — locally. Files, notes, links, browser captures, activity and work history -in one extensible local-first workspace. +in one extensible local-first workbench. **English** · [Русский](README.ru.md) @@ -29,7 +29,7 @@ in one extensible local-first workspace. Verstak is a local-first workbench that keeps the context around your work in one place. -A **workspace** can represent almost anything: +A **Deal** can represent almost anything: * a software project; * a client or customer; @@ -47,11 +47,11 @@ No account, cloud service or sync server is required for local use. ## Verstak in use -| Overview: return to a workspace and see its recent work, captures and items that need attention. | Files: manage ordinary folders and documents inside a workspace. | +| Overview: return to a Deal and see its recent work, captures and items that need attention. | Files: manage ordinary folders and documents inside a Deal. | | --- | --- | -| ![Verstak Overview in a test vault](docs/screenshots/overview.png) | ![Verstak workspace files in a test vault](docs/screenshots/workspace-files.png) | +| ![Verstak Overview in a test vault](docs/screenshots/overview.png) | ![Verstak Deal files in a test vault](docs/screenshots/workspace-files.png) | -| Notes: keep Markdown notes next to the workspace they describe. | Journal: record a completed session and retain its context. | +| Notes: keep Markdown notes next to the Deal they describe. | Journal: record a completed session and retain its context. | | --- | --- | | ![Verstak notes in a test vault](docs/screenshots/notes.png) | ![Verstak journal in a test vault](docs/screenshots/journal.png) | @@ -59,17 +59,17 @@ No account, cloud service or sync server is required for local use. | Feature | Description | | ------------------------ | -------------------------------------------------------------------------------------------- | -| **Workspaces** | Organize files, notes and activity around durable projects, clients and other areas of work. | +| **Deals** | Organize files, notes and activity around durable projects, clients and other areas of work. | | **Files** | Browse and manage ordinary files stored inside your vault. | | **Notes** | Create Markdown notes, overview pages and links between related information. | | **Overview** | Quickly return to recent work and see what may need attention. | | **Browser Inbox** | Send pages, links, selections and files from a browser into Verstak. | | **Activity and Journal** | Reconstruct work sessions and turn selected activity into journal entries. | -| **Todo** | Keep optional task lists inside individual workspaces and across the whole vault. | +| **Todo** | Keep optional task lists inside individual Deals and across the whole vault. | | **Search** | Search across notes, files and supported plugin data. | | **Trash** | Restore deleted items or remove them permanently from one central location. | -| **Secrets** | Keep credentials and access information connected to the relevant workspace. | -| **Templates** | Create repeatable workspace structures for common types of work. | +| **Secrets** | Keep credentials and access information connected to the relevant Deal. | +| **Templates** | Create repeatable Deal structures for common types of work. | | **Plugins** | Add, replace or disable tools without turning Verstak into one rigid monolithic application. | | **Optional sync** | Synchronize vaults between devices using a self-hosted Verstak Sync Server. | @@ -151,9 +151,9 @@ Documents/ Your files and notes remain ordinary files that can be accessed without Verstak. -### 2. Create your first workspace +### 2. Create your first Deal -Inside the vault, create a workspace for a project, client, server, device or another area of work. +Inside the vault, create a Deal for a project, client, server, device or another area of work. For example: @@ -167,7 +167,7 @@ Training course ### 3. Add context -Open the workspace and add the information needed to return to it later: +Open the Deal and add the information needed to return to it later: * notes and decisions; * documents and source files; @@ -245,15 +245,15 @@ for distribution-specific dependencies. The desktop, SDK and official plugin repositories must be cloned as sibling directories: ```text -verstak-workspace/ +verstak-source/ ├── verstak/ ├── verstak-sdk/ └── verstak-official-plugins/ ``` ```bash -mkdir verstak-workspace -cd verstak-workspace +mkdir verstak-source +cd verstak-source git clone https://github.com/mirivlad/verstak.git git clone https://github.com/mirivlad/verstak-sdk.git diff --git a/README.ru.md b/README.ru.md index fd4abce..65dd21e 100644 --- a/README.ru.md +++ b/README.ru.md @@ -244,15 +244,15 @@ sha256sum -c SHA256SUMS --ignore-missing Desktop, SDK и официальные плагины должны находиться в соседних каталогах: ```text -verstak-workspace/ +verstak-source/ ├── verstak/ ├── verstak-sdk/ └── verstak-official-plugins/ ``` ```bash -mkdir verstak-workspace -cd verstak-workspace +mkdir verstak-source +cd verstak-source git clone https://github.com/mirivlad/verstak.git git clone https://github.com/mirivlad/verstak-sdk.git diff --git a/docs/PLUGIN_RUNTIME.md b/docs/PLUGIN_RUNTIME.md index e8fe6bf..616b11b 100644 --- a/docs/PLUGIN_RUNTIME.md +++ b/docs/PLUGIN_RUNTIME.md @@ -464,7 +464,7 @@ contributions summary. Conflicts are rejected unless `options.overwrite` is true. - `files.deleteTrash(trashId)` — permanently removes a file/folder already in internal trash. This operation cannot be undone. -- UI policy: the workspace `Files` plugin displays only live files and folders. +- UI policy: the Deal `Files` plugin displays only live files and folders. The global official `verstak.trash` plugin owns listing, restoring, filtering, and permanently deleting deleted items across the vault. - `files.openExternal(relativePath)` — opens a vault-relative file/folder in @@ -635,7 +635,7 @@ bundled runtime. Это реальный runtime contract для cooperative bun 1. Unregister contributions всех plugins предыдущего discovery. 2. Unregister all non-core capabilities. -3. Re-register core capabilities + vault + workspace (если открыт). +3. Re-register core capabilities + vault + Deal manager (если открыт). 4. Re-scan discovery directories и повторить capability resolution. 5. Register contributions для loaded/degraded plugins (disabled/failed — не регистрируются). 6. Update plugins list. @@ -838,51 +838,52 @@ Vault plugin state хранится **внутри vault** в `.verstak/plugins. - `./scripts/smoke-platform.sh` — ✅ (enable/disable/plugins.json) - `./scripts/build.sh` — ✅ -## Workspace Core Capability +## Дело: core capability -Workspace — это физическая папка верхнего уровня внутри vault root. Filesystem -является source of truth для списка workspaces. +Дело — это физическая папка верхнего уровня внутри vault root. Filesystem +является source of truth для списка Дел. Пример: ``` / - Workspace/ + Deal/ Notes/ Project/ ClientA/ .verstak/ ``` -Нет единого `/Workspace/` контейнера для всех workspaces. Папка -`Workspace/` может быть обычным workspace, но `Project/` и `ClientA/` являются -такими же workspace на том же уровне. +Нет единого `/Deal/` контейнера для всех Дел. Папка `Deal/` может быть +обычным Делом, но `Project/` и `ClientA/` являются такими же Делами на том же +уровне. ### Хранение -Workspace existence/list хранится только в filesystem: +Существование и список Дел хранятся только в filesystem: - `ListWorkspaces()` читает top-level directories из vault root. - `.verstak`, reserved/internal directories, top-level files и symlinks не - считаются workspaces. -- `.verstak/workspace*.json` не является source of truth для списка workspaces. -- Нет persisted workspace path mapping и нет virtual workspace tree, которое + считаются Делами. +- `.verstak/workspace*.json` не является source of truth для списка Дел. +- Нет virtual workspace tree, которое мапится на произвольные папки. `.verstak` может хранить только metadata, которая не заменяет filesystem: -- UI state: selected workspace, expanded folders, sort/pin state, preferences. +- UI state: выбранное Дело, expanded folders, sort/pin state, preferences. - Semantic snapshot: applied template snapshot, enabled feature areas, exact `workspaceTools`, and folder conventions. -Template snapshot копируется в metadata при создании workspace. Workspace -identity при этом остаётся именем top-level folder; `metadata.workspaceName` -является presentation/snapshot field, not canonical identity. Если сохранённое -значение расходится с именем папки, runtime возвращает canonical `workspaceName` -равным имени папки без filesystem side effects. +При создании Дела runtime генерирует UUID и сохраняет его в +`.verstak/workspace.json`. `workspaceId` — постоянная личность Дела; +`workspaceRootPath` и `workspaceName` — изменяемый адрес и presentation fields. +Переименование обновляет путь, но не ID. Новая папка с прежним именем получает +другой ID и не может перехватить старые привязки. ```json { + "workspaceId": "1eb7cc69-52e8-4a18-ae2a-50d5229c5b60", "workspaceName": "Project", "createdFromTemplate": { "templateId": "project", @@ -921,25 +922,25 @@ identity при этом остаётся именем top-level folder; `metada } ``` -Если original template удалён или изменён позже, существующий workspace +Если original template удалён или изменён позже, существующее Дело открывается по сохранённому snapshot и не мутирует автоматически. Template update/migration может быть только явной future feature. Если metadata -отсутствует, workspace открывается как generic workspace минимум с `files: true`. +отсутствует, Дело открывается как generic Deal минимум с `files: true`. ### API -- `ListWorkspaces()` — список top-level physical folders. +- `ListWorkspaces()` — список top-level папок Дел с их `workspaceId`. - `ListWorkspaceTemplates()` — selectable built-in templates с presentation metadata и `workspaceTools`. - `CreateWorkspace(name, templateId?)` — создать `//`, применить template один раз, сохранить snapshot metadata. -- `RenameWorkspace(oldName, newName)` — физически переименовать top-level folder - и обновить metadata key/name. -- `TrashWorkspace(name)` — перенести весь top-level workspace folder в internal +- `RenameWorkspace(oldName, newName)` — физически переименовать top-level папку + Дела и обновить metadata name, не меняя `workspaceId`. +- `TrashWorkspace(name)` — перенести весь top-level folder Дела в internal trash policy. - `GetWorkspaceMetadata(name)` — прочитать metadata или вернуть generic fallback. - `UpdateWorkspaceMetadata(name, patch)` — обновить metadata без влияния на - существование workspace. + существование Дела. Deprecated compatibility APIs: @@ -949,7 +950,7 @@ Deprecated compatibility APIs: - `ArchiveWorkspaceNode(...)` — wrapper over `TrashWorkspace`. - `MoveWorkspaceNode(...)` — unsupported; old nested/mapped moves are rejected. - `GetCurrentWorkspaceNode()` / `SetCurrentWorkspaceNode(...)` — wrappers over - selected top-level workspace UI state. + selected top-level Deal UI state. Эти методы существуют только для постепенного frontend/Wails cleanup. Они не должны создавать или сохранять nested workspace tree и не должны восстанавливать @@ -957,32 +958,33 @@ Deprecated compatibility APIs: ### Capability -`verstak/core/workspace/v1` — регистрируется только когда vault открыт и workspace инициализирован. +`verstak/core/workspace/v1` — техническое имя capability; оно регистрируется +только когда vault открыт и Deal manager инициализирован. ### Правила -- Workspace name — один safe folder name, не path. +- Имя Дела — один safe folder name, не path. - Reject: empty, slash, backslash, absolute-looking paths, `..`, null byte, - `.verstak`, reserved/internal names, symlink workspaces, conflicts. -- WorkspaceItems получают `workspaceRootPath`, равный имени top-level папки + `.verstak`, reserved/internal names, symlink Дел, conflicts. +- WorkspaceItems получают техническое поле `workspaceRootPath`, равное имени top-level папки (`Project`, `ClientA`, etc). Files plugin показывает именно эту папку. - Files API остаётся raw vault-relative API: `Project/Notes/example.md`, `Project/docs/file.md`, `Test/readme.md`. -- Notes are ordinary Markdown files under `/Notes/`; нет +- Notes are ordinary Markdown files under `/Notes/`; нет `.verstak/notes`, UUID note storage или второго source of truth для note content. ### Lifecycle Events -Runtime publishes workspace lifecycle events after successful operations: +Runtime publishes lifecycle events Дел после успешных операций: -- `workspace.created` — payload includes `operation: "create"`, +- `workspace.created` — payload includes `operation: "create"`, `workspaceId`, `workspaceRootPath`, `workspaceName`, and optional `templateId`. -- `workspace.renamed` — payload includes `operation: "rename"`, new - `workspaceRootPath` / `workspaceName`, and previous workspace fields. -- `workspace.trashed` — payload includes `operation: "trash"`, +- `workspace.renamed` — payload includes `operation: "rename"`, `workspaceId`, + new `workspaceRootPath` / `workspaceName`, and previous path fields. +- `workspace.trashed` — payload includes `operation: "trash"`, `workspaceId`, `workspaceRootPath`, `workspaceName`, `trashId`, `trashPath`, and `deletedAt`. -- `workspace.selected` — payload includes `operation: "select"`, +- `workspace.selected` — payload includes `operation: "select"`, `workspaceId`, `workspaceRootPath`, and `workspaceName`. Official Activity subscribes to these events and stores them through the normal @@ -990,11 +992,11 @@ activity provider path. ### UI -Workspace list в sidebar: -- Flat list of top-level workspace folders. -- Create workspace, rename workspace, trash workspace. -- Selection is stored as selected workspace name. -- No expand/collapse workspace tree and no case/folder node creation in core. +Список Дел в sidebar: +- Flat list of top-level папок Дел. +- Создать Дело, переименовать Дело, переместить Дело в корзину. +- Selection is stored as selected Deal name. +- No expand/collapse tree and no case/folder node creation in core. --- diff --git a/docs/WORKSPACE_TEMPLATES.md b/docs/WORKSPACE_TEMPLATES.md index 126ec31..919c5f3 100644 --- a/docs/WORKSPACE_TEMPLATES.md +++ b/docs/WORKSPACE_TEMPLATES.md @@ -1,12 +1,12 @@ -# Workspace Templates +# Deal Templates -Workspace templates choose which dynamic plugin workspace tabs are visible when a -new top-level workspace is created. They do not enable or disable plugins for the +Deal templates choose which dynamic plugin Deal tabs are visible when a new +top-level Deal is created. They do not enable or disable plugins for the whole vault and do not affect global sidebar tools. ## Built-in templates -| Template | Workspace tabs | +| Template | Deal tabs | | --- | --- | | General | Notes, Files, Journal, Activity, Browser Inbox | | Project | Notes, Files, Todos, Journal, Activity, Browser Inbox | @@ -14,27 +14,27 @@ whole vault and do not affect global sidebar tools. | Admin | Notes, Files, Secrets, Todos, Journal | | Minimal | Notes, Files | -The create-workspace modal displays the selected template description and its +The create-Deal modal displays the selected template description and its included plugin tabs before the folder is created. ## Metadata and compatibility Creation stores a template snapshot in `.verstak/workspaces/` metadata. The snapshot contains the template id, name, version, applied time, and an ordered -`workspaceTools` list of plugin IDs. Existing workspace metadata without -`workspaceTools` remains compatible: its workspace continues to show all globally -enabled workspace plugins rather than unexpectedly hiding tabs. +`workspaceTools` list of plugin IDs. Existing Deal metadata without +`workspaceTools` remains compatible: its Deal continues to show all globally +enabled Deal plugins rather than unexpectedly hiding tabs. Templates are applied once. Editing the built-in catalog or creating another -workspace with a different template never changes an existing workspace snapshot. +Deal with a different template never changes an existing Deal snapshot. There is no template editor or post-creation template switcher yet. ## Global tools and unavailable plugins -Template visibility applies only to `workspaceItems` in the selected workspace. +Template visibility applies only to `workspaceItems` in the selected Deal. Global views and sidebar items, such as global Todos, Browser Inbox, and Trash, remain available according to the normal plugin enablement state. -The workspace host intersects the snapshot with dynamically discovered, globally +The Deal host intersects the snapshot with dynamically discovered, globally enabled plugin contributions. If a template references a plugin that is missing or disabled, that tab is simply absent; the other template tabs remain usable.