# Workspace Operations

The workspace server provides a web interface for content that does not fit well in the CLI. Managed via `ws.mjs`; always use the CLI, never raw process commands.


## When to use the workspace

- Long-form content (reports, documentation, analysis)
- Structured data (tables, comparisons)
- Content that benefits from formatting (HTML, styled text)
- Dashboards and status overviews


## Managing the workspace server

```
node core/tools/workspace/ws.mjs start [--port N] [--no-open]   # Start as background daemon
node core/tools/workspace/ws.mjs stop                            # Stop the server
node core/tools/workspace/ws.mjs restart [--port N] [--no-open]  # Stop then start
node core/tools/workspace/ws.mjs status                          # Show status (PID, port, uptime)
node core/tools/workspace/ws.mjs open                            # Open browser to server URL
```

Port resolution order: default 4200 -> `operator/config/preferences.json` key `workspacePort` -> `--port` CLI flag.

Do NOT use `lsof`, `kill`, or raw process management to manage the workspace server. `ws.mjs` handles all of this cross-platform.

Content served by the workspace is read fresh on every request, so file edits are picked up on browser refresh (Cmd+R / Ctrl+R). Live-reload / SSE has been temporarily removed pending a workspace rebuild; refresh the browser manually to see changes. You only need to restart the server when `server.mjs` or `api.mjs` themselves are modified.


## Available pages

- `/home.html`; dashboard overview
- `/projects.html`; project cards with detail drill-down
- `/project-detail.html`; single project view with work items
- `/tasks.html`; work item management
- `/knowledge.html`; knowledge browser
- `/secrets.html`; secrets management UI
- `/schedules.html`; scheduled/recurring tasks
- `/viewer.html?file=path/to/file.md`; generic content viewer (renders markdown to HTML)
- `/onboarding.html`; first-run setup (normally used once)


## Extending the workspace

Custom pages go in `operator/extensions/workspace/`. The server serves files from both `core/tools/workspace/app/` and the extensions directory.