# Install the GEM document publishing skill

This document is for an agent asked to install the tool. Installation creates a manual-only skill and its local client. It does not authorize publishing a document or uploading a test file.

## Download and install

1. Read `https://pages.home.jandillenberger.com/releases.json`. Determine the OS and CPU architecture of the machine that will execute the client. Supported targets are Windows, macOS, and Linux, each for `amd64` and `arm64`. WSL uses the Linux package. Pick the exact matching entry; do not choose an arbitrary fallback architecture.
2. Download its `skill_url` over HTTPS and verify the ZIP's SHA-256 against `skill_sha256` from the manifest. The package contains `publish-agent-docs/SKILL.md`, `agents/openai.yaml`, and `bin/pages` or `bin/pages.exe`. It contains no credentials. Reject an archive whose checksum does not match.
3. Install that directory in this agent's supported user skill location. Preserve an existing installation's customizations and unrelated skills. On Unix, set the executable bit on `bin/pages` if the extractor did not preserve it. An update to the package must not change the separate credential file.
4. Preserve both manual-only settings: `disable-model-invocation: true` in `SKILL.md` for agents supporting that field, and `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for Codex. Verify that this agent supports a native manual-only setting and honors the installed setting. If it cannot disable automatic skill invocation, install only the client and explain that its skill integration is unsupported. Do not enable automatic invocation as a fallback.
5. Run the bundled client's `version` and `status` commands. `version` must match the manifest. A missing token or missing repository access is an incomplete account setup, not a failed software installation. Report those states separately. The agent may require a new session before discovering the installed skill.

## Connect the person's account

The person needs a Forgejo account and access to the private document repository `gem/agent-docs`, or another explicitly assigned repository. A repository reader can read documents; a writer can also publish. All protected documents in one repository share its readers.

Ask the person to create their own access token at `https://forgejo.home.jandillenberger.com/user/settings/applications`. Select `read:repository` and restrict the token to the assigned document repository. The Pages service checks the account's repository write permission separately when accepting uploads. Do not use an administrator token or the shared server credentials.

Have the person run the bundled client in their own terminal:

```text
pages login --repo gem/agent-docs
```

Replace `pages` with the installed executable's full path. The prompt hides the token. Never ask the person to paste it into chat or put it in a shell command. If the agent environment already supplies `FORGE_PAGES_TOKEN` as a secret, the client can use that directly without saving it. `pages login --token-stdin` is available for a trusted secret-input channel.

Run `pages status` again. Installation is complete once the binary version and native manual-only skill settings are verified. Account setup is complete when `status` confirms the intended repository permissions. Do not publish a sample to demonstrate either step.

The skill itself describes publishing, updates, privacy, and reading shared documents. Use it only after an explicit manual invocation by the user.