docs: describe Deals as the user-facing unit
This commit is contained in:
parent
f9b20d51ff
commit
41aeefc182
30
README.md
30
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. |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|  |  |
|
||||
|
||||
| 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. |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 для списка Дел.
|
||||
|
||||
Пример:
|
||||
|
||||
```
|
||||
<vault>/
|
||||
Workspace/
|
||||
Deal/
|
||||
Notes/
|
||||
Project/
|
||||
ClientA/
|
||||
.verstak/
|
||||
```
|
||||
|
||||
Нет единого `<vault>/Workspace/` контейнера для всех workspaces. Папка
|
||||
`Workspace/` может быть обычным workspace, но `Project/` и `ClientA/` являются
|
||||
такими же workspace на том же уровне.
|
||||
Нет единого `<vault>/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?)` — создать `<vault>/<name>/`, применить
|
||||
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 `<workspace>/Notes/`; нет
|
||||
- Notes are ordinary Markdown files under `<Deal>/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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue