paperhub-workspace

name	paperhub-workspace
description	Initialize a PaperHub workspace and create research projects

PaperHub Workspace

Use this skill when the user wants to start using PaperHub, initialize a local workspace, or create a new research project.

What this skill does

• Initializes a PaperHub workspace with the canonical directory layout
• Guides user through cloud sync configuration setup
• Creates project view folders under projects/
• Sets up a self-contained Python virtual environment

Inputs it handles

• Workspace name
• Workspace path
• Project name or slug

Workflow

Step 1: Check for existing sync configuration

Before running any commands, check if the user has a sync configuration file (.env.paperhub.local).

Check these locations:

• {paperhub-repo}/.env.paperhub.local (if PaperHub was cloned)
• ~/.env.paperhub.local
• ~/.config/paperhub/.env.paperhub.local

Step 2: Ask user about sync configuration

If config found:

I found a sync configuration at: {path}
This enables PostgreSQL + OSS storage for syncing papers and metadata.

Do you want to use this configuration for your workspace?
- Yes: I'll copy it to the workspace (recommended for cloud sync)
- No: I'll skip it (workspace will use local-only storage)

If config NOT found:

No sync configuration found. You can sync papers and metadata to the cloud
using PostgreSQL + OSS, or keep everything local.

Do you want to configure cloud sync now?
- Yes: I'll help you create a .env.paperhub.local file
- No: Skip (local-only storage, no cloud sync)

If user chooses "No" to cloud sync:

Understood. Your workspace will use local file-based storage.
Note: You can configure cloud sync later by adding .env.paperhub.local
to your workspace directory.

Local storage locations:
- Metadata: .paperhub/remote/metadata/
- Blobs (PDFs): .paperhub/remote/blobs/

Step 3: Initialize workspace

1. Confirm workspace path with user (or use default like ~/paperhub)
2. Run:

paperhub init --workspace <workspace-path> --name "<workspace-name>"

3. The init command automatically:
   • Creates canonical directory layout
   • Sets up .venv/ with PaperHub and SSL certificates
   • Copies sync config if found and user agreed to use it

Step 4: Verify sync backend (if configured)

After init, verify the config was detected:

paperhub sync-status --workspace <workspace-path>

If pending_count > 0 and backends show "postgres" + "oss" → sync is ready.

Step 5: Create project (optional)

If the user wants a project:

paperhub create-project --workspace <workspace-path> --project <project-slug>

Sync Configuration Format

A .env.paperhub.local file should contain:

PAPERHUB_SYNC_BACKEND_MODE=real
PAPERHUB_PG_HOST=<your-postgres-host>
PAPERHUB_PG_PORT=5432
PAPERHUB_PG_DB=<your-db-name>
PAPERHUB_PG_USER=<your-db-user>
PAPERHUB_PG_PASSWORD=<your-db-password>
PAPERHUB_PG_SSLMODE=disable
STORAGE_TYPE=oss
OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com
OSS_BUCKET=<your-bucket-name>
OSS_ACCESS_KEY_ID=<your-access-key>
OSS_ACCESS_KEY_SECRET=<your-secret-key>
OSS_REGION=cn-beijing

Operational rules

• Treat the workspace as the user's paper library, not as the tool repository root.
• Never push paper data to GitHub.
• Always verify sync configuration before claiming cloud sync is available.
• If no config is present, default to local file-based storage.