Workspace files

This is the portable on-disk contract used by local and self-hosted Worktable. Worktable Cloud exposes the same content through .wtb export rather than a direct server filesystem.

The shape

<workspace>/                      default ~/Worktable
  worktable.workspace.json        workspace manifest
  threads/
    <thread-id>.json              Worktable-level conversations
  spaces/
    <space-id>/
      space.json                  space metadata
      docs/
        <doc-path>.md             markdown docs
        <doc-path>.json           rich (BlockNote) docs
      docs.meta.json              doc archive state and provenance
      doc-aliases.json            rename aliases for old doc paths and folders
      widgets.meta.json           HTML doc provenance
      widgets/
        <widget-id>/
          widget.yaml             HTML doc metadata and archive state
          index.html              the widget itself
          state.yaml              durable widget-local state
      records/
        <collection-id>/
          schema.yaml             optional collection schema
          <record-id>.yaml        one record per file
      annotations/
        docs/
          <doc-path>.annotations.json
        widgets/
          <widget-id>.annotations.json
      threads/
        <thread-id>.json          Space-level conversations
    .trash/                       recoverable deleted content
  versions/
    <space-id>/
      docs/<doc-path>/            doc version history
      widgets/<widget-id>/        HTML doc version history

What this buys you

Copy the folder or move it in a .wtb package and its portable meaning remains. Grep it, back it up, put it in git, or read it without Worktable running. Docs are Markdown, JSON, or self-contained HTML; records are YAML; thread and annotation envelopes are JSON.

Editing by hand

Safe and supported: doc .md files, record .yaml files, HTML doc index.html. Worktable watches the folder — external edits show up live in the app and to agents.

Treat as Worktable’s bookkeeping (editable, but easy to get wrong): worktable.workspace.json, space.json, docs.meta.json, widgets.meta.json, doc-aliases.json, .annotations.json, thread JSON, and versions/. Prefer doing those operations through the app or the MCP tools. Freshness and review status are derived from version history instead of being user-authored metadata.

What is deliberately not here

Machine-local state, including install data, CLI config, Worktable-managed token and password hashes, participant bindings, thread delivery state, service logs, realtime edit state, and caches, lives in the app data folder (macOS Application Support, or ~/.config/worktable). The rule: if copying the workspace should preserve its meaning, it is in the workspace; if it is security-sensitive, install-specific, or rebuildable, it is not. User-authored content can still contain secrets, so review it before sharing or committing the folder.

For the archive boundary and import limits, see workspace packages.