@pokelo/cli 0.1.3 → 0.2.0

package/README.md

@@ -20,7 +20,7 @@ From this monorepo (before publish / local dev):
 ```bash
 pnpm --filter @pokelo/cli exec pokelo --help
 # or
-node tools/pokelo-cli/bin/pokelo.mjs --help
+node tools/pokelo-cli/bin/pokelo --help
 
 cd tools/pokelo-cli && pnpm link --global
 pokelo --help
@@ -70,9 +70,9 @@ pokelo auth status
 ### Config priority
 
 ```text
-CLI flags (--url, --token, --project)
-  > environment (POKELO_URL, POKELO_TOKEN, POKELO_PROJECT)
-  > ~/.config/pokelo/config.json
+CLI flags (--url, --token, --project, --workspace)
+  > environment (POKELO_URL, POKELO_TOKEN, POKELO_PROJECT, POKELO_WORKSPACE)
+  > ~/.config/pokelo/config.json  (url, token, defaultProjectId, defaultWorkspaceId)
   > legacy ~/.pokelo-cli.json (read-only migrate of url/token)
 ```
 
@@ -83,8 +83,13 @@ Create a Personal Access Token in the Pokelo UI (Settings → MCP / PAT). Prefix
 ## Commands
 
 ```bash
-pokelo projects list
+pokelo workspace list
+pokelo workspace show <id>
+pokelo workspace use <id>       # save as default (written to config.json)
+
+pokelo projects list [--workspace <id>]
 pokelo projects get <project-id-or-slug>
+pokelo projects create --name "My Project" [--workspace <id>] [--description "..."]
 
 pokelo search "how does auth work" --project <ref> --limit 5
 
@@ -93,6 +98,10 @@ pokelo docs get <document-id-or-slug> --project <ref>
 pokelo docs create --title "Note" --type Note --content "# Hi" --project <ref>
 pokelo docs update <id> --content-file ./body.md --project <ref>
 
+pokelo docs versions <id> --project <ref> --limit 20
+pokelo docs version <id> 7 --project <ref> --raw
+pokelo docs restore <id> 7 --project <ref> --expect-head 9 --include-title
+
 pokelo assets list --project <ref>
 pokelo assets get <asset-id> --project <ref>
 pokelo assets upload ./shot.png --project <ref> --description "screenshot"
@@ -103,7 +112,18 @@ pokelo assets delete <asset-id> --project <ref>
 
 `assets upload` uses `POST …/assets/base64` for files ≤ 8 MiB; larger files use init → PUT → complete.
 
-Stdout is always JSON. Errors go to stderr.
+### Version history
+
+`docs versions` lists snapshots newest first (any project member, viewers included). `docs version <n>`
+returns one snapshot with its markdown body; `--raw` prints just the body. `docs restore <n>` makes an old
+snapshot the new head — content always, title only with `--include-title` — and requires write access
+(owner/admin/member). Pass `--expect-head <n>` (the `versionNo` you last saw) to get a `CONFLICT` error
+instead of overwriting somebody else's newer edit.
+
+The version subcommands also accept the explicit `<project> <document>` positional form, e.g.
+`pokelo docs versions khirby article-ideas-d692f34a`.
+
+Stdout is always JSON, except `docs version --raw`. Errors go to stderr.
 
 Exit codes: `0` ok, `1` usage/config, `2` API/network.
 
@@ -111,6 +131,9 @@ Exit codes: `0` ok, `1` usage/config, `2` API/network.
 
 ```bash
 pokelo auth login --url https://pokelo.example.com --token "$TOKEN"
+pokelo workspace list                          # discover workspaces
+pokelo workspace use <workspace-id>            # set default (optional)
+pokelo projects list                           # list projects (filtered by default workspace if set)
 pokelo search "jak działa auth" --project khirby --limit 5
 pokelo docs get <document-id> --project khirby
 pokelo assets upload ./diagram.png --project khirby

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pokelo/cli",
-  "version": "0.1.3",
-  "description": "Official Pokelo CLI \u2014 public REST client for agents and developers",
+  "version": "0.2.0",
+  "description": "Official Pokelo CLI \u2014 public REST client for agents and developers (multi-workspace)",
   "type": "module",
   "bin": {
     "pokelo": "bin/pokelo"

package/skill/SKILL.md

@@ -1,98 +1,306 @@
 ---
 name: pokelo-cli
 description: >-
-  Uses the Pokelo CLI (`pokelo` binary from npm package `@pokelo/cli`) over the
-  public REST API for auth, projects, semantic search, documents, and assets.
-  Use when working with Pokelo knowledge bases from the shell, provisioning
-  agents without MCP, or when the user mentions pokelo CLI, @pokelo/cli, or
-  PAT-based Pokelo access.
-disable-model-invocation: false
+  Use the official Pokelo CLI (`pokelo` binary from npm package `@pokelo/cli`)
+  to access Pokelo through the public REST API using Personal Access Tokens.
+  Trigger when working with Pokelo knowledge bases from the shell, provisioning
+  agents without MCP, configuring self-hosted Pokelo instances, searching or
+  reading project knowledge, creating or updating Pokelo documents, managing
+  assets, or when the user mentions Pokelo CLI, `pokelo`, `@pokelo/cli`,
+  Pokelo PAT access, `POKELO_URL`, or `POKELO_TOKEN`.
 ---
 
 # Pokelo CLI
 
-Official shell client for Pokelo. Speaks **public REST `/v1` + Personal Access Token** — never MCP.
+Use the official `pokelo` shell client for Pokelo.
 
-| Concept | Value |
-|---------|--------|
-| npm package | `@pokelo/cli` |
-| Command on PATH | `pokelo` |
-| Config | flags > `POKELO_*` env > `~/.config/pokelo/config.json` |
+The CLI talks to the **public REST `/v1` API using a Personal Access Token**.
 
-## 1. Ensure installed (idempotent)
+**Never use MCP as the transport for this skill.**
 
-Run before the first `pokelo` call in a session:
+## Core rules
+
+* Use the existing `pokelo` binary when available.
+* If `pokelo` is not available on `PATH`, install it with `npm install -g @pokelo/cli`.
+* Never reinstall the CLI when `pokelo` is already available.
+* Use the public REST API only.
+* Never echo, print, log, or expose access tokens.
+* Prefer environment variables in CI, sandboxes, and ephemeral agent environments.
+* Support self-hosted Pokelo instances by treating the instance URL as part of auth configuration.
+* Prefer semantic search before listing large document trees.
+* Fetch the full document only when search snippets are insufficient.
+* Perform write operations only when the user explicitly asks to create, update, upload, or delete something.
+* After creating or updating a Pokelo document, return its direct URL when the CLI response provides one.
+
+## 1. Ensure CLI availability
+
+Before the first `pokelo` call in a session:
+
+```bash
+command -v pokelo >/dev/null 2>&1 || npm install -g @pokelo/cli
+```
+
+Then use:
 
 ```bash
-# From package install or checkout:
-bash skill/scripts/ensure-pokelo.sh
-# Or: command -v pokelo || npm install -g @pokelo/cli
+pokelo ...
 ```
 
-Or manually:
+Do not use helper install scripts.
 
-1. If `command -v pokelo` succeeds → **do not install**; use it.
-2. Else: `npm install -g @pokelo/cli` (exposes the `pokelo` binary).
-3. In this monorepo only, if npm package is unpublished: use
-   `node tools/pokelo-cli/bin/pokelo.mjs` or symlink it to `~/.local/bin/pokelo`.
+Do not reinstall `@pokelo/cli` if `pokelo` already exists on `PATH`.
 
-Never reinstall when `pokelo` is already available.
+If installation fails, stop and report the installation error instead of falling back to MCP.
 
 ## 2. Auth
 
-Prefer env in CI / ephemeral sandboxes (no disk write):
+Pokelo may be self-hosted, so always treat the instance URL and token as configuration.
+
+Configuration priority:
+
+```text
+explicit CLI flags
+> POKELO_* environment variables
+> ~/.config/pokelo/config.json
+> defaults
+```
+
+### Ephemeral / CI / sandbox
+
+Prefer environment variables:
 
 ```bash
-export POKELO_URL=https://<host>          # or http://localhost:3001 for local API
-export POKELO_TOKEN=mcp_…                 # Personal Access Token
-export POKELO_PROJECT=<slug-or-uuid>      # optional default
+export POKELO_URL=https://pokelo.example.com
+export POKELO_TOKEN=...
+export POKELO_PROJECT=<slug-or-uuid>   # optional
 ```
 
-Or persist config (agents, headless):
+### Persistent agent configuration
 
 ```bash
-pokelo auth login --url "$POKELO_URL" --token-stdin <<< "$POKELO_TOKEN"
-# or: pokelo auth login --url … --token "$TOKEN"
-pokelo auth status   # never prints the full token
+pokelo auth login \
+  --url "$POKELO_URL" \
+  --token-stdin <<< "$POKELO_TOKEN"
 ```
 
-Local Vite (`:5173`) does **not** proxy `/v1` — point `POKELO_URL` at the API (`:3001`), not the frontend.
+Direct token form:
+
+```bash
+pokelo auth login \
+  --url https://pokelo.example.com \
+  --token "$TOKEN"
+```
+
+Use `--token-stdin` when practical because process arguments may be visible to other processes.
+
+Verify:
+
+```bash
+pokelo auth status
+```
+
+`auth status` must never reveal the full token.
+
+## 3. Resolve the workspace (when needed)
+
+Some commands accept an optional `--workspace <id>` filter. Resolution order:
+
+1. `--workspace <id>` flag (or `-w <id>`)
+2. `POKELO_WORKSPACE` environment variable
+3. `defaultWorkspaceId` in `~/.config/pokelo/config.json`
+4. Auto-detect: if exactly one workspace, use it; otherwise error
 
-## 3. Commands (stdout = JSON)
+Set the default workspace for all future commands:
+
+```bash
+pokelo workspace list         # list available workspaces
+pokelo workspace use <id>     # save as defaultWorkspaceId
+```
+
+Show or verify a specific workspace:
+
+```bash
+pokelo workspace show <id>
+```
+
+## 4. Resolve the project
+
+When the project is unknown or ambiguous:
+
+```bash
+pokelo projects list [--workspace <id>]
+```
+
+Then:
 
 ```bash
-pokelo projects list
 pokelo projects get <project-ref>
+```
+
+Create a project (workspace admin required):
+
+```bash
+pokelo projects create --name "My Project" [--workspace <id>] [--description "..."]
+```
 
-pokelo search "<query>" --project <ref> [--limit n]
+Prefer an already known project slug or `POKELO_PROJECT` when available.
 
-pokelo docs list --project <ref>
-pokelo docs get <doc-ref> --project <ref>
-pokelo docs create --title "…" [--type] [--content|--content-file] [--parent] --project <ref>
-pokelo docs update <doc-ref> [--title] [--content|--content-file] --project <ref>
+Do not repeatedly list projects when the correct project is already known.
 
-pokelo assets list --project <ref>
-pokelo assets get <asset-id> --project <ref>
-pokelo assets upload <file> [--name] [--mime] [--visibility] [--document] [--description] --project <ref>
-pokelo assets download <asset-id> --out <path> --project <ref>
-pokelo assets update <asset-id> [--name] [--description] … --project <ref>
-pokelo assets delete <asset-id> --project <ref>
+## 4. Read knowledge
+
+Use semantic search first:
+
+```bash
+pokelo search "<query>" --project <project-ref> --limit 10
 ```
 
-Exit codes: `0` ok, `1` usage/config, `2` API/network. Errors on stderr.
+Typical workflow:
+
+```text
+search
+-> inspect matches
+-> docs get when more context is needed
+-> answer
+```
+
+Fetch the full document only when needed:
+
+```bash
+pokelo docs get <document-ref> --project <project-ref>
+```
+
+List documents only when semantic search is not sufficient:
+
+```bash
+pokelo docs list --project <project-ref>
+```
+
+Avoid dumping large document trees into model context unless necessary.
+
+## 5. Write knowledge
+
+Only write when explicitly requested or when the user clearly asks to persist durable project knowledge.
+
+### Create
+
+```bash
+pokelo docs create \
+  --title "Document title" \
+  --project <project-ref> \
+  --content-file ./document.md
+```
+
+Optional fields may include:
+
+```text
+--type
+--parent
+--content
+--content-file
+```
+
+### Update
+
+```bash
+pokelo docs update <document-ref> \
+  --project <project-ref> \
+  --content-file ./document.md
+```
+
+Prefer updating an existing relevant document instead of creating a duplicate.
+
+After successful create or update, return the direct Pokelo document URL from the CLI response when available.
+
+Do not store:
+
+* credentials,
+* API keys,
+* passwords,
+* access tokens,
+* temporary debugging output,
+* unconfirmed speculation.
+
+### Version history
+
+Every write to a document creates a snapshot. Use history to inspect what changed and to undo a bad edit
+instead of retyping the old body.
+
+```bash
+pokelo docs versions <document-ref> --project <project-ref> [--page <n>] [--limit <n>]
+pokelo docs version <document-ref> <version-no> --project <project-ref> [--raw]
+pokelo docs restore <document-ref> <version-no> --project <project-ref> [--expect-head <n>] [--include-title]
+```
+
+Notes:
+
+* `versions` returns snapshots newest first with `versionNo`, `createdAt`, `createdBy`, `createdVia`
+  (`editor` / `api` / `mcp` / `assist` / `import` / `sync` / `conflict_resolve` / `restore` / `system`),
+  `contentSize` and `isCurrent` — not the body.
+* `version` returns one snapshot including `contentMd`; `--raw` prints only the markdown body.
+* `restore` creates a NEW head version from an old one — nothing is deleted. Content is always restored,
+  the title only with `--include-title`. Requires project write access (owner / admin / member).
+* Read the current `versionNo` first and pass it as `--expect-head`; a `CONFLICT` error then means somebody
+  edited the document in the meantime — re-read the history instead of retrying blindly.
+* Restore only when the user asked to undo or roll back.
+
+## 6. Assets
+
+Use asset commands when the user asks to work with files stored in Pokelo.
+
+```bash
+pokelo assets list --project <project-ref>
+pokelo assets get <asset-id> --project <project-ref>
+pokelo assets upload <file> --project <project-ref> [options]
+pokelo assets download <asset-id> --out <path> --project <project-ref>
+pokelo assets update <asset-id> --project <project-ref> [options]
+pokelo assets delete <asset-id> --project <project-ref>
+```
+
+Do not expose storage implementation details unless debugging the CLI itself.
+
+## 7. Output handling
+
+Treat stdout as machine-readable JSON unless documented otherwise (`docs version --raw` prints markdown).
+
+Rules:
+
+* parse stdout,
+* send errors to stderr,
+* use exit status to distinguish success from failure,
+* do not rely on decorative terminal output,
+* never expose secrets in errors.
+
+Expected exit codes:
+
+```text
+0 = success
+1 = usage or configuration error
+2 = API or network error
+```
 
-`assets upload`: ≤ 8 MiB → `POST …/base64`; larger → init → PUT → complete.
+## 8. Recommended agent workflow
 
-## 4. Agent workflow
+1. Check whether `pokelo` exists.
+2. If not, install `@pokelo/cli`.
+3. Resolve auth from flags, environment, or persisted config.
+4. Resolve the project.
+5. Run semantic search.
+6. Fetch the full document if needed.
+7. Answer from retrieved knowledge.
+8. Write only when requested.
+9. Return Pokelo document URLs after successful creates or updates.
 
-1. Ensure `pokelo` is installed (step 1).
-2. Confirm auth (`auth status` or env vars).
-3. Resolve project (`projects list` / known slug).
-4. `search` → if snippets are thin, `docs get`.
-5. Write only when asked (`docs create/update`, `assets upload`).
-6. Do **not** echo tokens; do **not** call MCP from this skill.
+## 9. Prohibited behavior
 
-## 5. Extra detail
+Do not:
 
-- Command cheat sheet: [reference.md](reference.md)
-- This directory is the copy shipped inside the `@pokelo/cli` npm package (`skill/`).
+* reinstall `@pokelo/cli` when `pokelo` already exists,
+* use helper installer scripts,
+* call the Pokelo MCP endpoint,
+* construct MCP JSON-RPC requests,
+* fall back from REST to MCP,
+* print or expose PATs,
+* list large document sets when semantic search is enough,
+* create duplicate documentation when an existing document should be updated,
+* perform writes without user intent.

package/src/cli.mjs

@@ -4,6 +4,8 @@ import { runAuth } from './commands/auth.mjs';
 import { runDocs } from './commands/docs.mjs';
 import { runProjects } from './commands/projects.mjs';
 import { runSearch } from './commands/search.mjs';
+import { runSearchWorkspace } from './commands/search-workspace.mjs';
+import { runWorkspace } from './commands/workspace.mjs';
 
 function printHelp() {
   process.stdout.write(
@@ -15,15 +17,24 @@ Usage:
   pokelo auth login
   pokelo auth status
 
-  pokelo projects list
+  pokelo workspace list
+  pokelo workspace show <id>
+  pokelo workspace use <id>
+
+  pokelo projects list [--workspace <id>]
   pokelo projects get <project-id-or-slug>
+  pokelo projects create --name <name> [--workspace <id>] [--description <text>]
 
   pokelo search "<query>" [--project <ref>] [--limit <n>]
+  pokelo search-workspace "<query>" [--per-project-limit <n>]
 
   pokelo docs list [--project <ref>]
   pokelo docs get <document-id-or-slug> [--project <ref>]
   pokelo docs create --title <t> [--type] [--content|--content-file] [--parent] [--project]
   pokelo docs update <document-id-or-slug> [options]
+  pokelo docs versions [<project>] <document> [--page <n>] [--limit <n>]
+  pokelo docs version [<project>] <document> <version-no> [--raw]
+  pokelo docs restore [<project>] <document> <version-no> [--expect-head <n>] [--include-title]
 
   pokelo assets list [--project] [--type] [--visibility] [--document]
   pokelo assets get <asset-id> [--project]
@@ -33,14 +44,16 @@ Usage:
   pokelo assets delete <asset-id> [--project]
 
 Global options:
-  --project, -p <ref>   Project UUID or slug (or POKELO_PROJECT / config default)
-  --url <url>           Instance URL (overrides env/config)
-  --token <token>       Personal Access Token (overrides env/config; prefer env/--token-stdin)
-  --json                Accepted for compatibility (stdout is always JSON)
-  --help, -h            Show help
+  --project, -p <ref>     Project UUID or slug (or POKELO_PROJECT / config default)
+  --workspace, -w <id>    Workspace UUID (or POKELO_WORKSPACE / config defaultWorkspaceId)
+  --url <url>             Instance URL (overrides env/config)
+  --token <token>         Personal Access Token (overrides env/config; prefer env/--token-stdin)
+  --json                  Accepted for compatibility (stdout is always JSON, except docs version --raw)
+  --raw                   docs version: print the markdown body instead of JSON
+  --help, -h              Show help
 
 Config (priority: flags > env > file):
-  POKELO_URL, POKELO_TOKEN, POKELO_PROJECT
+  POKELO_URL, POKELO_TOKEN, POKELO_PROJECT, POKELO_WORKSPACE
   ~/.config/pokelo/config.json
 
 Exit codes: 0 ok, 1 usage/config, 2 API/network error
@@ -79,6 +92,14 @@ export function parseArgs(argv) {
       flags.tree = true;
       continue;
     }
+    if (arg === '--raw') {
+      flags.raw = true;
+      continue;
+    }
+    if (arg === '--include-title') {
+      flags.includeTitle = true;
+      continue;
+    }
 
     const eq = arg.match(/^--([a-zA-Z0-9-]+)=(.*)$/);
     if (eq) {
@@ -90,6 +111,10 @@ export function parseArgs(argv) {
       flags.project = needValue(argv, ++i, arg);
       continue;
     }
+    if (arg === '--workspace' || arg === '-w') {
+      flags.workspace = needValue(argv, ++i, arg);
+      continue;
+    }
     if (arg === '--limit' || arg === '-l') {
       flags.limit = parseInt(needValue(argv, ++i, arg), 10);
       continue;
@@ -98,6 +123,17 @@ export function parseArgs(argv) {
       flags.page = parseInt(needValue(argv, ++i, arg), 10);
       continue;
     }
+    if (arg === '--expect-head') {
+      flags.expectHead = parseInt(needValue(argv, ++i, arg), 10);
+      continue;
+    }
+    if (arg === '--per-project-limit') {
+      const raw = needValue(argv, ++i, arg);
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 1) fail(`--per-project-limit must be a positive integer, got: ${raw}`);
+      flags['per-project-limit'] = n;
+      continue;
+    }
     if (arg === '--url') {
       flags.url = needValue(argv, ++i, arg);
       continue;
@@ -180,8 +216,10 @@ function needValue(argv, index, flag) {
 function setFlag(flags, name, value) {
   const map = {
     project: 'project',
+    workspace: 'workspace',
     limit: 'limit',
     page: 'page',
+    'expect-head': 'expectHead',
     url: 'url',
     token: 'token',
     title: 'title',
@@ -190,6 +228,7 @@ function setFlag(flags, name, value) {
     'content-file': 'contentFile',
     parent: 'parent',
     status: 'status',
+    'per-project-limit': 'per-project-limit',
     search: 'search',
     name: 'name',
     mime: 'mime',
@@ -203,8 +242,12 @@ function setFlag(flags, name, value) {
   };
   const key = map[name];
   if (!key) fail(`unknown option: --${name}`);
-  if (key === 'limit' || key === 'page') {
+  if (key === 'limit' || key === 'page' || key === 'expectHead') {
     flags[key] = parseInt(value, 10);
+  } else if (key === 'per-project-limit') {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) fail(`--per-project-limit must be a positive integer, got: ${value}`);
+    flags[key] = n;
   } else {
     flags[key] = value;
   }
@@ -231,12 +274,18 @@ export async function main(argv) {
     case 'auth':
       await runAuth(rest, flags);
       break;
+    case 'workspace':
+      await runWorkspace(rest, flags);
+      break;
     case 'projects':
       await runProjects(rest, flags);
       break;
     case 'search':
       await runSearch(rest, flags);
       break;
+    case 'search-workspace':
+      await runSearchWorkspace(rest, flags);
+      break;
     case 'docs':
       await runDocs(rest, flags);
       break;

package/src/commands/docs.mjs

@@ -26,6 +26,33 @@ function resolveContent(flags) {
   return undefined;
 }
 
+/**
+ * Version subcommands accept both `<document>` (project from --project/config) and the
+ * explicit `<project> <document>` form. `trailing` counts the args that follow the document.
+ *
+ * @param {string[]} rest - positionals after the subcommand
+ * @param {number} trailing
+ * @returns {{ projectRef: string | null, docRef: string | undefined, tail: string[] }}
+ */
+function splitVersionRefs(rest, trailing) {
+  if (rest.length > 1 + trailing) {
+    return { projectRef: rest[0], docRef: rest[1], tail: rest.slice(2) };
+  }
+  return { projectRef: null, docRef: rest[0], tail: rest.slice(1) };
+}
+
+function requireVersionNo(value) {
+  const parsed = typeof value === 'string' ? parseInt(value, 10) : NaN;
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    fail('<version-no> must be a positive integer (see: pokelo docs versions)');
+  }
+  return parsed;
+}
+
+function versionsPath(project, docRef) {
+  return `/projects/${encodeURIComponent(project)}/documents/${encodeURIComponent(docRef)}/versions`;
+}
+
 /**
  * @param {string[]} positional
  * @param {Record<string, unknown>} flags
@@ -34,15 +61,66 @@ export async function runDocs(positional, flags) {
   const sub = positional[0];
   if (!sub) {
     fail(
-      'Usage: pokelo docs <list|get|create|update>\n' +
+      'Usage: pokelo docs <list|get|create|update|versions|version|restore>\n' +
         '  pokelo docs list [--project <ref>]\n' +
         '  pokelo docs get <id-or-slug> [--project <ref>]\n' +
         '  pokelo docs create --title <t> [--type] [--content|--content-file] [--parent] [--project]\n' +
-        '  pokelo docs update <id-or-slug> [--title] [--content|--content-file] [--project]',
+        '  pokelo docs update <id-or-slug> [--title] [--content|--content-file] [--project]\n' +
+        '  pokelo docs versions [<project>] <document> [--page <n>] [--limit <n>]\n' +
+        '  pokelo docs version [<project>] <document> <version-no> [--raw]\n' +
+        '  pokelo docs restore [<project>] <document> <version-no> [--expect-head <n>] [--include-title]',
     );
   }
 
   const config = resolveConfig(flags);
+  const rest = positional.slice(1);
+
+  if (sub === 'versions' || sub === 'version' || sub === 'restore') {
+    const trailing = sub === 'versions' ? 0 : 1;
+    const { projectRef, docRef, tail } = splitVersionRefs(rest, trailing);
+    if (!docRef) {
+      fail(
+        sub === 'versions'
+          ? 'Usage: pokelo docs versions [<project>] <document-id-or-slug>'
+          : `Usage: pokelo docs ${sub} [<project>] <document-id-or-slug> <version-no>`,
+      );
+    }
+    const project = projectRef ?? requireProject(config, flags);
+    const base = versionsPath(project, docRef);
+
+    if (sub === 'versions') {
+      const data = await apiRequest(config, 'GET', base, {
+        query: {
+          page: typeof flags.page === 'number' ? flags.page : undefined,
+          limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        },
+      });
+      writeJson(data);
+      return;
+    }
+
+    const versionNo = requireVersionNo(tail[0]);
+
+    if (sub === 'version') {
+      const data = await apiRequest(config, 'GET', `${base}/${versionNo}`);
+      if (flags.raw === true && flags.json !== true) {
+        process.stdout.write(`${data?.contentMd ?? ''}\n`);
+        return;
+      }
+      writeJson(data);
+      return;
+    }
+
+    const body = {};
+    if (typeof flags.expectHead === 'number' && Number.isInteger(flags.expectHead)) {
+      body.expectedHeadVersionNo = flags.expectHead;
+    }
+    if (flags.includeTitle === true) body.includeTitle = true;
+    const data = await apiRequest(config, 'POST', `${base}/${versionNo}/restore`, { body });
+    writeJson(data);
+    return;
+  }
+
   const project = requireProject(config, flags);
 
   if (sub === 'list') {

package/src/commands/projects.mjs

@@ -1,4 +1,4 @@
-import { resolveConfig } from '../config.mjs';
+import { resolveConfig, resolveWorkspaceId } from '../config.mjs';
 import { fail, writeJson } from '../exit.mjs';
 import { apiRequest } from '../http.mjs';
 
@@ -11,12 +11,17 @@ export async function runProjects(positional, flags) {
   const config = resolveConfig(flags);
 
   if (sub === 'list' || !sub) {
+    const workspaceId =
+      (typeof flags.workspace === 'string' && flags.workspace.trim()) ||
+      config.defaultWorkspaceId ||
+      undefined;
     const data = await apiRequest(config, 'GET', '/projects', {
       query: {
         page: typeof flags.page === 'number' ? flags.page : undefined,
         limit: typeof flags.limit === 'number' ? flags.limit : undefined,
         q: typeof flags.search === 'string' ? flags.search : undefined,
         status: typeof flags.status === 'string' ? flags.status : undefined,
+        workspaceId,
       },
     });
     writeJson(data);
@@ -31,5 +36,19 @@ export async function runProjects(positional, flags) {
     return;
   }
 
-  fail(`unknown projects command: ${sub}\nUsage: pokelo projects <list|get>`);
+  if (sub === 'create') {
+    const name = typeof flags.name === 'string' ? flags.name.trim() : '';
+    if (!name) fail('Usage: pokelo projects create --name <name> [--workspace <id>]');
+    // Order: --workspace / env / config → auto if exactly one membership → error
+    const workspaceId = await resolveWorkspaceId(config, apiRequest, { requireWorkspace: true });
+    const body = { workspaceId, name };
+    if (typeof flags.description === 'string' && flags.description.trim()) {
+      body.description = flags.description.trim();
+    }
+    const data = await apiRequest(config, 'POST', '/projects', { body });
+    writeJson(data);
+    return;
+  }
+
+  fail(`unknown projects command: ${sub}\nUsage: pokelo projects <list|get|create>`);
 }

package/src/commands/search-workspace.mjs

@@ -0,0 +1,22 @@
+import { resolveConfig } from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runSearchWorkspace(positional, flags) {
+  const query = positional[0];
+  if (!query) fail('Usage: pokelo search-workspace "<query>" [--per-project-limit <n>]');
+  const config = resolveConfig(flags);
+  const perProjectLimit =
+    typeof flags['per-project-limit'] === 'number' ? flags['per-project-limit'] : undefined;
+  const data = await apiRequest(config, 'POST', '/documents/search-workspace', {
+    body: {
+      query,
+      ...(perProjectLimit !== undefined ? { perProjectLimit } : {}),
+    },
+  });
+  writeJson(data);
+}

package/src/commands/workspace.mjs

@@ -0,0 +1,53 @@
+import { loadPersistedConfig, resolveConfig, saveConfig, xdgConfigPath } from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runWorkspace(positional, flags) {
+  const sub = positional[0];
+
+  if (!sub || sub === 'list') {
+    const config = resolveConfig(flags);
+    const data = await apiRequest(config, 'GET', '/workspaces');
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'show') {
+    const id = positional[1];
+    if (!id) fail('Usage: pokelo workspace show <id>');
+    const config = resolveConfig(flags);
+    const data = await apiRequest(config, 'GET', `/workspaces/${encodeURIComponent(id)}`);
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'use') {
+    const id = positional[1];
+    if (!id) fail('Usage: pokelo workspace use <id>');
+    const config = resolveConfig(flags);
+    // Verify the workspace is accessible before saving
+    const data = await apiRequest(config, 'GET', `/workspaces/${encodeURIComponent(id)}`);
+    const existing = loadPersistedConfig();
+    const path = saveConfig({
+      url: config.url,
+      token: config.token,
+      defaultProjectId: existing?.defaultProjectId ?? null,
+      defaultWorkspaceId: id,
+    });
+    writeJson({
+      ok: true,
+      defaultWorkspaceId: id,
+      workspaceName: data?.name ?? id,
+      configPath: path,
+    });
+    return;
+  }
+
+  fail(
+    `unknown workspace command: ${sub}\nUsage:\n  pokelo workspace list\n  pokelo workspace show <id>\n  pokelo workspace use <id>`,
+  );
+}

package/src/config.mjs

@@ -6,7 +6,7 @@ import { fail } from './exit.mjs';
 
 const LEGACY_CONFIG_PATH = join(homedir(), '.pokelo-cli.json');
 
-/** @typedef {{ url: string, token: string, defaultProjectId?: string | null }} PokeloConfig */
+/** @typedef {{ url: string, token: string, defaultProjectId?: string | null, defaultWorkspaceId?: string | null }} PokeloConfig */
 
 export function xdgConfigPath() {
   const xdg = process.env.XDG_CONFIG_HOME?.trim();
@@ -77,13 +77,17 @@ function sanitizeFileConfig(obj) {
     typeof obj.defaultProjectId === 'string' && obj.defaultProjectId.trim()
       ? obj.defaultProjectId.trim()
       : null;
+  const defaultWorkspaceId =
+    typeof obj.defaultWorkspaceId === 'string' && obj.defaultWorkspaceId.trim()
+      ? obj.defaultWorkspaceId.trim()
+      : null;
   if (!url && !token) return null;
-  return { url, token, defaultProjectId };
+  return { url, token, defaultProjectId, defaultWorkspaceId };
 }
 
 /**
  * Resolve runtime config.
- * @param {{ url?: string, token?: string, project?: string }} flags
+ * @param {{ url?: string, token?: string, project?: string, workspace?: string }} flags
  */
 export function resolveConfig(flags = {}) {
   const file = loadPersistedConfig();
@@ -102,6 +106,11 @@ export function resolveConfig(flags = {}) {
     process.env.POKELO_PROJECT?.trim() ||
     file?.defaultProjectId ||
     null;
+  const workspace =
+    (typeof flags.workspace === 'string' && flags.workspace.trim()) ||
+    process.env.POKELO_WORKSPACE?.trim() ||
+    file?.defaultWorkspaceId ||
+    null;
 
   if (!urlRaw) fail('missing Pokelo URL (set --url, POKELO_URL, or run: pokelo auth login)');
   if (!token) fail('missing access token (set --token, POKELO_TOKEN, or run: pokelo auth login)');
@@ -110,9 +119,37 @@ export function resolveConfig(flags = {}) {
     url: normalizeApiBaseUrl(urlRaw),
     token,
     defaultProjectId: project,
+    defaultWorkspaceId: workspace,
   };
 }
 
+/**
+ * Resolve workspace context from flags + config + optional auto-detection.
+ * Resolution order: --workspace flag → config defaultWorkspaceId → auto (single membership) → error.
+ * @param {{ url: string, token: string, defaultWorkspaceId: string | null }} config
+ * @param {import('./http.mjs').apiRequest} apiRequest
+ * @param {{ workspace?: string, requireWorkspace?: boolean }} opts
+ * @returns {Promise<string | null>}
+ */
+export async function resolveWorkspaceId(config, apiRequest, opts = {}) {
+  if (config.defaultWorkspaceId) return config.defaultWorkspaceId;
+  if (!opts.requireWorkspace) return null;
+
+  // Auto-detect: list workspaces and pick if exactly 1 membership
+  let data;
+  try {
+    data = await apiRequest(config, 'GET', '/workspaces');
+  } catch {
+    fail('workspace_id required: use --workspace, POKELO_WORKSPACE, or: pokelo workspace use <id>');
+  }
+  const items = Array.isArray(data?.items) ? data.items : [];
+  if (items.length === 1) return items[0].id;
+  if (items.length === 0) fail('no workspaces found; contact your admin');
+  fail(
+    `multiple workspaces found — specify one:\n  pokelo workspace use <id>\n  --workspace <id>\n\nAvailable workspaces:\n${items.map((w) => `  ${w.id}  ${w.name}`).join('\n')}`,
+  );
+}
+
 /**
  * Persist config to XDG path. Never logs the token.
  * @param {{ url: string, token: string, defaultProjectId?: string | null }} cfg
@@ -124,6 +161,7 @@ export function saveConfig(cfg) {
     url: normalizeApiBaseUrl(cfg.url),
     token: String(cfg.token).trim(),
     defaultProjectId: cfg.defaultProjectId?.trim() || null,
+    defaultWorkspaceId: cfg.defaultWorkspaceId?.trim() || null,
   };
   writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
   try {

package/skill/reference.md

@@ -1,59 +0,0 @@
-# Pokelo CLI reference
-
-## Package vs binary
-
-```text
-npm i -g @pokelo/cli   →  installs package @pokelo/cli
-                       →  binary name: pokelo
-```
-
-## Config priority
-
-```text
---url / --token / --project
-  > POKELO_URL / POKELO_TOKEN / POKELO_PROJECT
-  > ~/.config/pokelo/config.json
-  > legacy ~/.pokelo-cli.json (read for migration on login)
-```
-
-URL forms `https://host` and `https://host/v1` both normalize to `…/v1`.
-
-## Auth
-
-| Command | Notes |
-|---------|--------|
-| `pokelo auth login --url U --token T` | Persist config; never echo T |
-| `pokelo auth login --url U --token-stdin` | Token from stdin |
-| `pokelo auth login` | Interactive TTY only |
-| `pokelo auth status` | Masked preview `mcp_…****` |
-
-## Projects / search / docs
-
-| Command | REST |
-|---------|------|
-| `projects list` | `GET /projects` |
-| `projects get <ref>` | `GET /projects/:id` |
-| `search "q" -p <ref> -l n` | `POST /projects/:id/documents/search` |
-| `docs list -p <ref>` | `GET /projects/:id/documents` |
-| `docs get <ref> -p <ref>` | `GET /projects/:id/documents/:id` |
-| `docs create --title …` | `POST /projects/:id/documents` |
-| `docs update <ref> …` | `PATCH /projects/:id/documents/:id` |
-
-## Assets
-
-| Command | REST |
-|---------|------|
-| `assets list` | `GET /projects/:id/assets` |
-| `assets get <id>` | `GET /projects/:id/assets/:id` |
-| `assets upload <file>` | `POST …/base64` or uploads+complete |
-| `assets download <id> --out F` | get + downloadUrl / content redirect |
-| `assets update <id>` | `PATCH /projects/:id/assets/:id` |
-| `assets delete <id>` | `DELETE /projects/:id/assets/:id` |
-
-Filters for list: `--type`, `--source`, `--visibility`, `--document`, `--page`, `--limit`.
-
-## Safety
-
-- Never print the full PAT.
-- Prefer `--token-stdin` or env over `--token` when possible.
-- Do not commit `~/.config/pokelo/config.json`.

package/skill/scripts/ensure-pokelo.sh

@@ -1,47 +0,0 @@
-#!/usr/bin/env bash
-# Ensure the `pokelo` binary is on PATH. No-op if already available.
-# npm package name: @pokelo/cli  →  CLI command: pokelo
-set -euo pipefail
-
-if command -v pokelo >/dev/null 2>&1; then
-  echo "pokelo already available: $(command -v pokelo)"
-  exit 0
-fi
-
-if command -v npm >/dev/null 2>&1; then
-  echo "Installing @pokelo/cli (provides \`pokelo\` binary)…"
-  if npm install -g @pokelo/cli; then
-    if command -v pokelo >/dev/null 2>&1; then
-      echo "Installed: $(command -v pokelo)"
-      exit 0
-    fi
-    echo "Package installed but \`pokelo\` not on PATH; check npm global bin." >&2
-  else
-    echo "npm install -g @pokelo/cli failed (package may be unpublished)." >&2
-  fi
-fi
-
-# Monorepo / package-local fallbacks
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CANDIDATES=(
-  # skill shipped inside tools/pokelo-cli/skill/scripts
-  "$SCRIPT_DIR/../../bin/pokelo.mjs"
-  # .cursor/skills/pokelo-cli/scripts → repo tools/pokelo-cli
-  "$SCRIPT_DIR/../../../tools/pokelo-cli/bin/pokelo.mjs"
-)
-
-mkdir -p "${HOME}/.local/bin"
-for candidate in "${CANDIDATES[@]}"; do
-  if [[ -f "$candidate" ]]; then
-    ln -sfn "$candidate" "${HOME}/.local/bin/pokelo"
-    export PATH="${HOME}/.local/bin:${PATH}"
-    if command -v pokelo >/dev/null 2>&1; then
-      echo "Linked local CLI: $candidate → ~/.local/bin/pokelo"
-      exit 0
-    fi
-  fi
-done
-
-echo "Error: could not locate or install pokelo." >&2
-echo "Fix: npm install -g @pokelo/cli   OR   symlink tools/pokelo-cli/bin/pokelo.mjs" >&2
-exit 1