# Set up Workover

You are setting up Workover for the person you are working with. Workover is a documentation
platform: a shared editor for docs, API references and help centers, Workover AI drafting updates
from merged pull requests and support conversations, and publishing to a hosted Workover Help
Center or to WordPress, Webflow, Mintlify or Help Scout Docs.

You do almost all of it from a terminal, including the whole hosted Help Center: the project, the
import of their existing docs, the custom domain and publishing. The person does four things, in a
browser or at their DNS provider: they sign up and pay, approve your sign-in, connect GitHub if
they want Workover AI, and add the DNS records you give them. When you reach one of those, stop,
tell them exactly what to do, and wait for them to confirm before you go on.

## Rules

- Never ask the person to paste a password, a card number, an API key or a token into this
  conversation. Anything secret is entered by them, in the Workover app, in their browser. That
  includes their DNS provider's login: they add the records, you do not.
- Never read or copy `~/.workover/config.json`. The CLI and the MCP server use it for you.
- Do not call the Workover REST API directly. Use the `workover` CLI or the Workover MCP tools.
- Changes you make to existing documents should be suggestions for review (`workover doc propose`)
  unless the person asks you to edit directly.
- Payment is always the person's step. If a command says the plan does not include a hosted Help
  Center, tell them to choose a plan in Settings, Plan & billing, and wait.

## 1. Account and workspace (the person, in a browser)

Ask the person whether they already have a Workover account. If they do, skip to step 2.

If not, ask them to open https://workover.io/app/sign-up and sign up, with email or with
"Continue with Google". Onboarding then walks them through:

1. A little about themselves.
2. Creating a workspace.
3. Inviting their team (optional).
4. Billing details for the 14-day free trial. A card is required, and the trial includes every Pro
   feature. Payment is always the person's step: never offer to do it.
5. "Create your first project". They can stop here and tell you they are done: you create the
   project and its Help Center in step 4. If they already created one, you will use it.

## 2. Install and sign in to the Workover CLI (you, in a terminal)

The CLI needs Node.js 20 or later.

```sh
npm i -g @workover/cli
workover login --site
```

If you cannot install packages globally, run every command as `npx -y @workover/cli@latest <command>`
instead.

`workover login` uses a device authorization flow: it prints a short code and a link, and opens
the browser where it can. Your shell may give up before the person approves, so you can run
`workover login --site --no-wait` instead, which prints the code and the link and returns at once,
then `workover login --resume` once they say they approved.

Tell the person to open the link in the browser where they are signed in to the Workover account
they just created (not a work or test account they also use), check that the code matches, and
approve. The approval screen lists what the sign-in may do. `--site` adds "Set up and publish your
Workover Help Center": it lets you create the Help Center, import docs into it, connect its domain
and publish it. Tell them that is what they are approving.

When the sign-in completes, the CLI prints the account that approved it ("Signed in ... as
Sam <sam@example.com>") and its workspaces. `workover login --resume --json` prints the same as JSON
(`user.email`, `workspaces`). Then confirm the sign-in:

```sh
workover whoami
workover projects
```

`workover whoami` names the account (its email and name), its workspaces, and what the sign-in can
do (`site` should be in the list). `workover projects` lists the projects you can reach, with
their ids, and marks the ones that already have a Help Center.

**Check the account and the workspace before you create anything.** Read the email back to the
person and ask whether it is the account they meant, and check that the workspace they set up in
step 1 is in the list. A browser signed in to another account approves the code just the same, and
then everything you create lands in that account. If either is wrong, run `workover logout`, have
the person sign in to the right account in the browser, and run `workover login --site` again.

A normal login can read documents, create new ones and propose changes as suggestions. Other
permissions are opt-in, and the browser shows the person exactly what each one grants:

- `workover login --site`: set up and publish a hosted Help Center (the steps below).
- `workover login --write`: edit existing documents directly, with no suggestion to review.
- `workover login --publish`: publish to connected WordPress sites.
- `workover login --draft`: ask Workover AI to write drafts.

Only request the last three if the person asks for what they allow. Each login replaces the last
one, so ask for everything you need at once (`workover login --site --write`).

## 3. Connect the Workover MCP server (optional)

The MCP server gives you the same tools as the CLI: documents (search, read, create, propose
edits, the style guide) and the Help Center (`workover_create_project`, `workover_import_site`,
`workover_set_domain`, `workover_publish_site` and the rest). It uses the sign-in from step 2.

In Claude Code:

```sh
claude mcp add --scope user workover -- npx -y @workover/mcp@latest
workover install-claude
```

`workover install-claude` installs a skill that points Claude Code at Workover document links.

In another MCP client (Cursor, Codex and others), add a local stdio server named `workover` that
runs the command `npx` with the arguments `-y @workover/mcp@latest`.

A newly added MCP server is usually not available until the client restarts. Until then, use the
CLI, which works immediately.

## 4. Create the Help Center (you)

Look at what `workover projects` printed.

- **A project already marked Help Center** (made in onboarding): use its id.
- **A project without one**: give it a Help Center.

  ```sh
  workover site create --project <projectId>
  ```

  A project that syncs with WordPress, Webflow, Mintlify or Help Scout Docs cannot also have one
  (a project publishes one way). Create a new project instead.
- **No project yet**: create one that publishes to a Workover Help Center.

  ```sh
  workover project create --name "<name>" --start empty
  ```

  `--start empty` is for docs you will import in step 5. Use `--start starter` for the starter
  template, or `--start blank` for one empty page. Add `--workspace <slug>` when `workover whoami`
  lists more than one workspace.

Both give the site an address at `<name>.workover.site`, made from the name. When that one is taken
or reserved (generic words such as `docs`, and brand names, Workover's included), the command uses a
free alternative and prints it. Pass `--address <name>` to choose it; if that one is taken or
reserved, the command says so and names a free one to pass instead.
The command prints the project id: you need it for every command below. Nothing is public yet.

## 5. Bring in the existing docs (you)

Pick the route that matches where the docs live now.

- **A public docs site.** Import it, with its navigation and images (up to 500 pages):

  ```sh
  workover site import --project <projectId> --url https://docs.example.com
  ```

  It reads the site's own sidebar where it can (Mintlify, GitBook, VitePress, Workover and most
  others), so the pages keep their order and the Help Center opens on the site's first page. It
  waits and reports progress. A large site can outlast the wait: the command then says it is
  still running, and `workover site import --project <projectId> --status` checks again. Running
  the import again adds the pages the site does not have yet and keeps the ones it has.
- **A docs folder or repository on disk.** When it has a config that lays out the navigation
  (Workover's `_site.json` with `<tab>/<slug>.md` pages, or Mintlify's `docs.json`), import the
  folder as it is, with its tabs, groups and order exactly as the config says:

  ```sh
  workover site import --project <projectId> --dir <path-to-folder>
  ```

  Pages the site already has are kept, so running it again adds only what is new. Then set the
  site's colors and links from the same config, and its logo and favicon from the brand's image
  files (SVG, PNG, JPEG, WebP or ICO, under 2 MB), and add the redirects from its old addresses:

  ```sh
  workover site appearance --project <projectId> --from <path-to-folder> \
    --logo <logo.svg> --logo-dark <logo-dark.svg> --favicon <favicon.png>
  workover site redirects --project <projectId> --from <path-to-folder>
  ```

  The `--logo` flags are needed only when the config does not name the files. Both commands keep
  every setting they are not given, and the redirects command only adds. Through the MCP server
  the same steps are `workover_import_site` with `dir`, `workover_set_site_appearance` and
  `workover_add_site_redirects`.
- **Loose Markdown files on disk.** With no config, create the documents yourself, one per file:

  ```sh
  workover doc create --project <projectId> --title "<title>" --file <path-to-file.md>
  ```

  Use the page's first heading as the title, and start the body at `##`. The person can also
  upload `.md`, `.mdx` or `.txt` files (up to 200 at a time) in Settings, Writing and review,
  Import.
- **A Git repository.** Two-way Git sync works with GitHub and GitLab, for a repository of
  Markdown and MDX pages with a `docs.json` navigation file. It connects to the person's Git
  account, so they set it up in the project's settings under "Git sync", in the browser.

When the product has an OpenAPI (or Swagger) spec, add an API reference tab made from it, with one
page per endpoint, grouped by tag, and a Try it playground on each:

```sh
workover site api add --project <projectId> --spec https://api.example.com/openapi.json
```

The spec must be at an https URL, not a file on disk, because the site reads it again to stay in
step: every hour, and whenever `workover site api sync --project <projectId>` runs (suggest the
person adds that to their API's deploy, with a site token). New endpoints get a page, changed ones
are rewritten and removed ones redirect to the tab's first page. These generated pages publish
themselves once the site has been published; every other page still waits for the person. A
`_site.json` tab, or a `docs.json` tab or group, that names `"openapi": "<url>"` does the same
during the folder import. Through the MCP server: `workover_add_api_reference` and
`workover_sync_api_reference`.

Before you write anything, read the team's style guide and follow it:

```sh
workover rules list --project <projectId>
```

## 6. Connect GitHub so Workover AI drafts updates (the person, in a browser)

When a pull request merges, Workover AI finds the articles it touches and drafts the edits as
suggestions for a person to accept. To turn it on, ask the person to:

1. Open Settings, Connections, Integrations, and choose Connect for GitHub. This installs the
   Workover GitHub App on the repositories they pick.
2. Open Settings, Connections, AI, add their own Anthropic, OpenAI, OpenRouter or Z.ai key there
   (in the browser, never in this conversation), and turn on "Documentation reviewer".

The automatic agents are part of Pro, and of the free trial. Support inboxes (Zendesk, Intercom,
Help Scout, Freshdesk and Plain) connect from the same Integrations page, and turn repeated
questions into suggested articles.

## 7. Publish (you)

```sh
workover site publish --project <projectId>
```

It waits, then prints how many pages went live and where: `<name>.workover.site` straight away,
and the custom domain once its records are found (step 8). Publish again whenever the pages change.
If it says the plan does not include a hosted Help Center, that is the person's step: they choose a
plan in Settings, Plan & billing, then you publish again.

A new site asks search engines not to index it. Ask the person whether it should be found in
search; if so:

```sh
workover site index --project <projectId> on
```

## 8. Add a custom domain (you, then the person at their DNS provider)

Ask the person which address the docs should have: a subdomain such as `docs.example.com`, or a
path on their website such as `example.com/docs`. Then connect it:

```sh
workover site domain --project <projectId> --set docs.example.com
```

It prints every DNS record to add, as the app's Domain tab shows them: usually a TXT record that
proves the domain is theirs and a CNAME to `sites.workover.io`, each with the name to type into the
provider's form, the full name, and the value. **Give the person every record exactly as printed,
the TXT records included.** Adding them is their step: you can help them find where their DNS
provider keeps its records, but you do not sign in to it.

- If the domain already serves another site (they are moving their docs to Workover), add
  `--preverify`. It also prints TXT records that prove the domain and issue its certificate
  before the CNAME moves, so readers never meet a certificate error. Tell the person to add the
  TXT records first and the CNAME only once they are verified.
- For a path (`--set example.com/docs`), it prints one TXT record and the proxy their website
  needs to send `/docs` to the Help Center, for the platform the website runs on (read from its
  headers): a Cloudflare Worker, Vercel or Next.js rewrites, AWS CloudFront or Amplify, Netlify,
  nginx, Caddy or Apache. If the website's code is in the repository you are working in, add it
  there with `workover site proxy --project <projectId> --write` (`--platform <name>` if the
  guess is wrong); otherwise hand it to the person with the record.

Once they say the records are in, check:

```sh
workover site check --project <projectId>
```

It asks the DNS provider now and says which records are found, whether the domain is verified and
the certificate issued, and when it is live. DNS can take a few minutes, sometimes longer: check
again rather than changing anything. `workover site domain --project <projectId>` prints the
records again at any time.

## 9. Check the result

`workover site status --project <projectId>` sums up the site: its address, the domain, the last
import and publish. Once the site is live, open it and confirm the imported pages are there.
Every published page is also served as Markdown at its own address with `.md` added, and the site
publishes an `/llms.txt` index, so you can read it the way other AI tools will.

## 10. Hand off

Finish by telling the person what is set up and what is left for them, which is usually:

- Any DNS records still pending, repeated exactly as `workover site domain` prints them.
- Accepting or editing the suggestions waiting in the Inbox.
- Inviting teammates in Settings, Members.
- Choosing a plan in Settings, Plan & billing before the trial ends.

More: https://workover.io/docs
