Set up Pageship

Agents: read the plain Markdown at /setup-guide.md

Read this whole file before you change anything. If you only have a summary of it, download https://pageship.dev/setup-guide.md with curl or a similar command and read that instead.

Follow this guide when the user asks you to set up Pageship, or when the pageship skill sends you here. It installs the Pageship CLI and the Pageship skills, offers two recommended skills and the agent-browser tool, and signs the user in to Pageship.

Part of Pageship may already be installed, for example the skills without the CLI. Check first, then do only the steps that are missing.

1. Check what is installed

Change nothing in this step. Find out:

• Whether pageship is on the PATH: run pageship --version.
• If it is, whether a newer CLI is published: run npm view pageship version, or read version from https://registry.npmjs.org/pageship/latest. When that version is newer than pageship --version, plan to update the CLI in step 4. A skills value of current only means the skills match the installed CLI.
• If it is, run pageship --json status and read its result:
  • skills says whether the Pageship skills are missing, current, or older than the CLI. If the result has no skills field, the CLI is too old to install them, so plan to update it in step 4.
  • missing lists the recommended skills it didn’t find, frontend-design and design-taste-frontend. It can also list node, which you check yourself below.
  • status is admitted when the user is signed in and the workspace address is set.
• If pageship isn’t on the PATH, look for the skills yourself. The Pageship skills are installed when ~/.agents/skills/pageship exists. A recommended skill is installed when its folder is in ~/.agents/skills or ~/.claude/skills, or in the skills folder of a Claude Code plugin under ~/.claude/plugins/cache. On Windows, ~ is the user’s profile folder.
• The Node version: run node --version. The Pageship CLI needs Node 24.11 or later.
• Which package managers are on the PATH: npm, pnpm, bun.
• Which tools that install Node are on the PATH: Vite+ (vp), fnm, nvm, mise, volta, Homebrew, winget, or the system’s package manager.
• Whether agent-browser is on the PATH: run agent-browser --version.

2. Ask the user once

From the check, list every step below that is still needed, with the command each one will run. When step 4 is needed, list step 5 too, since the skills may need an update once the CLI is installed. Include the recommended skills that weren’t found, and say they are optional: they improve the look of documents, and Pageship doesn’t ship or update them. Include agent-browser when it wasn’t found, and say it is optional too: the Pageship skills use it to look at each document in a browser before they hand it over, and it downloads a browser of its own.

Show the list and ask the user once whether to go ahead, and whether to include the recommended skills and agent-browser. Change nothing before they answer. Then do the steps they agreed to, in order, without asking again. Signing in still needs the user: they approve it in the browser, and they may pick a workspace address.

If nothing is missing, tell the user Pageship is already set up and stop.

3. Install Node

Do this step only when Node is missing or older than 24.11.

Install a supported version, such as the current LTS, with a tool the system already has. Prefer a Node version manager the user already uses over a second way of installing Node. For example:

• Vite+: vp env default 24
• fnm: fnm install 24, then fnm default 24
• nvm: nvm install 24, then nvm alias default 24
• mise: mise use -g node@24
• volta: volta install node@24
• Homebrew: brew install node@24, then follow its note to put it on the PATH
• winget: winget install OpenJS.NodeJS.LTS

If a command differs in the user’s version of the tool, check its help. If the system has none of these tools, don’t install one. Tell the user, and ask them to install Node from https://nodejs.org.

Open a new shell, and check that node --version now reports a supported version.

4. Install the CLI

Do this step only when pageship isn’t on the PATH, when step 1 found it too old to report skills, or when a newer version is published.

Install it globally with the user’s package manager. To update it, use the package manager that installed it, so the PATH keeps a single pageship. The folder that command -v pageship prints, or where pageship on Windows, usually shows which one.

• npm: npm i -g pageship@latest
• pnpm: pnpm add -g pageship@latest
• bun: bun add -g pageship@latest
• Vite+: vp install -g pageship@latest

Then check that pageship --version runs. If the shell can’t find it, the package manager’s global folder isn’t on the PATH. Follow the manager’s own advice, for example pnpm setup, then open a new shell.

5. Install the Pageship skills

Do this step when the skills are missing or older, or when you installed or updated the CLI in step 4 and its status doesn’t report them as current. Run:

pageship --json skills install

On skills_installed, the skills are installed. On skills_modified, the CLI wrote nothing, because the folders listed in folders were changed after it installed them, or it has no record of them. Don’t run its resolutions.force, which would replace those folders and lose the changes. Report the folders at the end instead, and let the user decide.

6. Install the recommended skills

Do this step only for the recommended skills and agent-browser that weren’t found, and only if the user agreed to them. Install frontend-design first:

npx skills add anthropics/skills --skill frontend-design -g -y

Then design-taste-frontend. Install only that skill, not the whole Taste repository:

npx skills add Leonxlnx/taste-skill --skill design-taste-frontend -g -y

Then agent-browser. Install it, then download its browser:

npm i -g agent-browser
agent-browser install

On Linux, run agent-browser install --with-deps instead of agent-browser install, so it also installs the system libraries its browser needs. That command may need sudo; when it can’t run, report it for the user to run. Then check that agent-browser --version runs.

7. Sign in

Run:

pageship --json status

It returns one JSON object. If status isn’t admitted, show the user its message, run its next as pageship --json <command> <args...> with the args unchanged, and follow each result’s message and next until status returns admitted. On choice_required, ask the user to choose one of the hostname values in resolutions.select, then run that entry. Any other result without a next, such as unreachable or uninvited, ends the step: report its message and stop. A next of skills install is step 5, not part of signing in.

Setup ends here. Don’t publish a test document unless the user asks for one.

8. Report

Tell the user:

• what you installed, and which steps you skipped because they were already done or because the user declined them;
• anything that failed or needs their decision, such as the folders from skills_modified;
• the account and workspace address from the last status, in user.name and address.hostname;
• that they may need to start a new agent session before their agent loads the new skills.