SpecViber SaaS Client — Setup guide

How to connect a project on your machine to a hosted SpecViber workspace. The downloaded ZIP is reference code — settings live in .vscode/mcp.json in your own project, not in the unpacked folder.

Prerequisites

1. Download and unpack

Get the latest specviber-saas-client-<version>.zip from the Downloads page and extract it into a folder your web server can serve — for example C:\xampp\htdocs\specviber_saas_client\ for XAMPP. Remember the path — you'll need it in step 3.

Then install the MCP server's dependencies:

cd specviber_saas_client/mcp-server
npm install
cd ..

2. Create your workspace in the web UI

Open the SpecViber web UI and create a workspace there (if you haven't already). During workspace creation:

1. Give the workspace a name.
2. If the workspace will contain multiple repos, decide which one is your main repo / customization host. Put that repo first in the workspace repo list. That repo should carry .vscode/mcp.json, .github/local-instructions.md, deployed skills/agents, and the built copilot-instructions.md.
3. Point it at the local path where you unpacked the SaaS client in step 1.
4. Finish the setup. Copy the API token and write down the numeric workspace ID — both are shown once and you'll need them in step 3.

3. Copy and run the setup prompt in your project

Open the main repo / customization host in VS Code — not the SaaS client folder. The unpacked client is a background service; you don't open it for daily work.

Copy the prompt below into a text editor first, replace the placeholders, then paste the finished prompt into Copilot Chat:

CopyI want to connect this project to an existing SpecViber SaaS workspace.

The SaaS client folder is unpacked at: `C:/xampp/htdocs/specviber_saas_client`
API token from the web UI workspace setup: `<paste-token-from-step-2>`
Workspace ID from the web UI: `<paste-numeric-id-from-step-2>`

Replace the three values above before you run this prompt.

Do the following:

### 1. Configure MCP
Create `.vscode/mcp.json` in **this** project (use the SaaS client path from above):
```json
{
    "servers": {
        "specviber": {
            "type": "stdio",
            "command": "node",
            "args": ["C:/xampp/htdocs/specviber_saas_client/mcp-server/index.js"],
            "env": {
                "SPEVI_API_URL": "https://app.specviber.com",
                "SPEVI_CONTENT_URL": "http://localhost/specviber_saas_client",
                "SPEVI_API_TOKEN": "<paste-token-from-step-2>",
                "SPEVI_DEFAULT_WORKSPACE": "<paste-numeric-id>",
                "SPEVI_ALLOWED_WORKSPACES": "<paste-numeric-id>"
            }
        }
    }
}
```
Adjust the local path and token to match the values above.

### 2. Verify the existing workspace connection
Run `spevi_dashboard` and confirm that the workspace behind the token is reachable.

### 3. Scan markdown files
Run `spevi_scan` to index markdown files for this project.
If the workspace still points at the wrong local path, stop and tell me exactly what path must be corrected in the web UI.

### 4. Set up Copilot instructions
If this workspace has multiple repos: treat **this** repo as the customization host. Keep it first in the SpecViber workspace repo list.
If `.github/copilot-instructions.md` exists but `.github/local-instructions.md` does not: rename it to `local-instructions.md` to preserve project rules.
If neither exists: create `.github/local-instructions.md` with project-specific info (stack, key files, build/test commands).
Keep `local-instructions.md` short and repo-specific. Move shared workflows into skills/shared docs instead of duplicating big always-on instructions in every repo.
Then run `spevi_deploy_skills` to deploy shared instructions, skills, and agents.
Update `.github/local-instructions.md` with `<!-- spevi:workspaces X -->` using the active workspace ID.
Run `php build_instructions.php --profile saas` in **this** project (the file was deployed by `spevi_deploy_skills`) to generate the merged `copilot-instructions.md`.

### 5. Set up taxonomy and classify
Copy `<unpacked-client>/docs/specs/templates/INITIAL_ONBOARDING_TEMPLATE.md`
into this project as `docs/specs/INITIAL_ONBOARDING.md`. Then run:

```
spevi_batch { op: "register", file_path: "docs/specs/INITIAL_ONBOARDING.md", repo: "<your-repo>" }
spevi_pickup { id: <id-from-register-response> }
```

Work through the spec phase by phase (orchestrates #D1037 + #D1038 per #D1039).
@user-tagged checkboxes are confirmation gates. The spec is resumable.

### 6. Verify
Run `spevi_dashboard` and confirm workspace, files, and classifications are visible.

Start using it

Once setup is complete:

• Copilot Agent: switch to the spevi agent in VS Code Copilot Chat for task-driven work.
• Web UI: app.specviber.com/specviber.html — sign in and select your workspace.
• Kanban: app.specviber.com/kanban/kanban.html — manage tasks visually.

Architecture

Your project repo          SaaS client folder (background service)
  .md files ◄──────────── PHP API (local) ──────── Cloud DB
                              ▲
  VS Code ──── MCP ───────────┘

• Content (.md files, checkboxes, comments) → local disk in your project
• Metadata (tasks, status, relations) → managed cloud database
• MCP → proxies everything through the local PHP API in the SaaS client folder

What's in the unpacked ZIP:

Troubleshooting

Upgrading