# Overview

> Write leveling guides in plain text, test them in the playground and publish them as your own community addon.

Page: https://polestar.guide/docs/authors (Polestar docs > Guide authors)

Anyone can write guides for Polestar and publish them as their own addon, with
the tools Polestar uses for its own: the guide format, the compiler, `lint`,
`playtest`, and in the game the guide engine, the arrow and the map markers.
Hand over to any of Polestar's guides with `next`, so your guides can cover one
zone or the whole climb, under a license of your choice.

## A guide is plain text

Each guide is a `.guide` file: a header, then steps, each with its goals. The
compiler fills in names, titles and coordinates from the reference data, so a
line can be as short as `accept 783`.

Try it: edit the guide, and the guide window shows the step as a player sees it.

To start a community guide of your own:

```sh title="Terminal"
git clone https://github.com/fitzforge/polestar.git
cd polestar
npm link               # puts `polestar` on your PATH; no npm dependencies
polestar data build    # the reference data every guide command reads
polestar doctor        # checks the setup and prints the fix for anything missing
cd ..                  # your community guide goes beside the clone, not inside it
polestar new my-pack   # asks for the id, title, author and license
cd my-pack
polestar dev --play    # lint and build on every save, with the browser playground
```

## Publish on polestar.guide

A community guide is a folder: `pack.json` at its top and one `.guide` file
per route, with pictures in `.tga` or `.blp` if it has any. You publish its
source, never a built addon or Lua: the site builds the addon with Polestar's
own compiler.

Sign in and turn on two-step sign-in in Account settings › Sign-in & security
first: publishing needs it, so a stolen password alone can't send anything to
players. Then open [New community guide](https://polestar.guide/studio/new) and follow its five
steps:

1. **Id and title.** The id names the addon folder (`PolestarPack_<id>`) and
   starts every route's id; pack.json's `"id"` must match it. You can change
   it until a version has gone out to players.
2. **How you publish.** Upload here, or publish from GitHub Actions (below).
   An upload takes the folder or a zip of it (at most 10 MB zipped, 40 MB
   unpacked, 500 files). The page checks it in your browser before anything is
   sent, so a missing `pack.json` or a route under the wrong id shows at once.
3. **Build report.** The compiler checks every step against the game data, as
   `polestar lint` does, in a few seconds. Errors stop the build: fix them and
   upload again, with the same version number. Warnings don't. The built zip
   then goes to VirusTotal's malware scanners, which can take a few minutes.
4. **Listing.** A summary, a description, tags and pictures for the guide's
   page.
5. **Visibility.** Public, unlisted, or a draft only you and your co-authors
   see. You can publish while the first version still waits for a moderator:
   the guide goes live with your choice by itself once it is approved.

Everything saves as you go, so you can leave and finish later from
[Your guides](https://polestar.guide/account/guides), which shows where each guide is: in review,
scanning, public, unlisted or turned down (with the moderator's reason). For a
new version, raise `"version"` in pack.json and upload again from the guide's
**Versions** tab, or push a tag from GitHub Actions.

### What happens to each version

- **Build and checks.** A version that doesn't build never reaches anyone.
- **Malware scan.** A version is published only once its scan is clean.
- **Review.** A moderator looks at a guide's first version from each author,
  and at any later version that comes with a new owner or installs different
  addon folders, usually within a day. You hear the outcome in your
  notifications and by email. Other updates go out on their own.
- **Players.** Once published, players who download it from the site get it at
  once; the Polestar Client's automatic updates install it 24 hours later, so
  you have time to pull a bad version.
- **An email for every upload.** The guide's owner (and whoever uploaded it)
  gets a mail naming the version, who uploaded it and how. If it wasn't you or
  your co-authors, its **This wasn't me** link pulls the version from every
  player's client, revokes the token that sent it and tells the moderators.

Once a version has gone out to players, deleting the guide retires its id for
good: nobody can publish a guide with it again, so its players never get
someone else's updates.

### If your guide is reported

Players can report a guide, and rights-holders can send a copyright notice
about it. A moderator looks at each one. If a copyright notice holds up, the
guide is taken down: it is hidden on polestar.guide, every version is removed
from players' Polestar Clients, and you and your co-authors get an email with
the claim and who made it.

If you believe it was a mistake, send a counter-notice from the banner on the
guide's page in the studio. It is forwarded to the claimant, and unless they
tell us they have gone to court, the guide can be restored after 10 to 14
business days. The removed versions stay removed, so upload a new version once
it is back. A takedown that stands counts against your account, and repeated
infringement can close it. Details: [Copyright & takedowns](https://polestar.guide/legal/copyright).

## Publish from GitHub Actions

If your guide lives in a GitHub repository, a workflow can publish each release
for you: push a tag like `v1.2.0` and it uploads the guide folder with the same
checks and build as an upload in the studio. polestar.guide never reads your
repository; the workflow sends the source with a token for this one guide.

1. **Make a token.** In [Your guides](https://polestar.guide/account/guides), open the guide's
   **Publishing** tab (or pick **Publish from GitHub Actions** when you create
   it) and choose **Create a token for this guide**. It is shown once. A token
   can only upload new versions of that one guide: it can't change the listing,
   touch your other guides or your account. Only an owner of the guide can make
   one, from a session confirmed with two-step sign-in. It expires after 90 days
   unless you pick another time (a year at most), and every token goes when
   your password is reset. Account settings › Publish tokens lists yours, with
   their guide, expiry and last use, and revokes them.
2. **Add it to the repository** as a secret named `POLESTAR_TOKEN`: on GitHub,
   **Settings → Secrets and variables → Actions → New repository secret**.
3. **Add the workflow** as `.github/workflows/polestar.yml`. The Publishing tab
   has it with your guide's id filled in; for a guide with the id `my-guide` it
   is:

```yaml title=".github/workflows/polestar.yml"
# Publishes a new version of "My Guide" to polestar.guide when you push a tag like v1.2.0:
#   git tag -a v1.2.0 -m "What changed in this version"
#   git push origin v1.2.0
# The tag must match "version" in pack.json; the tag's message becomes the release notes.
# Needs the repository secret POLESTAR_TOKEN: this guide's publish token, made in the studio
# (Your guides > my-guide > Publishing).
name: Publish to Polestar

on:
  push:
    tags: ['v*']

permissions:
  contents: read

concurrency:
  group: polestar-publish

defaults:
  run:
    shell: bash

env:
  POLESTAR_URL: https://polestar.guide/api/packs/my-guide/versions
  # The folder with pack.json at its top, from the repository's root.
  GUIDE_DIR: .

jobs:
  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Read the release notes from the tag
        run: |
          git fetch --no-tags --depth=1 origin "+refs/tags/$GITHUB_REF_NAME:refs/tags/$GITHUB_REF_NAME"
          git for-each-ref --format='%(if:equals=tag)%(objecttype)%(then)%(contents:subject)%0a%0a%(contents:body)%(end)' "refs/tags/$GITHUB_REF_NAME" | head -c 5000 > "$RUNNER_TEMP/notes.txt"

      - name: Zip the guide folder
        working-directory: ${{ env.GUIDE_DIR }}
        run: |
          zip -q -r -D "$RUNNER_TEMP/guide.zip" . \
            -i 'pack.json' 'legs.json' 'retired.json' 'LICENSE*' 'README*' '*.guide' '*.tga' '*.blp' \
            -x 'dist/*' 'drafts/*' 'node_modules/*' '.*' '*/.*'
          unzip -l "$RUNNER_TEMP/guide.zip"

      - name: Upload to Polestar
        env:
          POLESTAR_TOKEN: ${{ secrets.POLESTAR_TOKEN }}
        run: |
          curl --fail-with-body --silent --show-error \
            -H "Authorization: Bearer $POLESTAR_TOKEN" \
            -F "files=@$RUNNER_TEMP/guide.zip" \
            -F "version=${GITHUB_REF_NAME#v}" \
            -F "changelog=<$RUNNER_TEMP/notes.txt" \
            "$POLESTAR_URL"
          echo

      - name: Wait for the build
        env:
          POLESTAR_TOKEN: ${{ secrets.POLESTAR_TOKEN }}
        run: |
          for i in $(seq 60); do
            build=$(curl --fail-with-body --silent --show-error --retry 6 --retry-delay 10 -H "Authorization: Bearer $POLESTAR_TOKEN" "$POLESTAR_URL/${GITHUB_REF_NAME#v}")
            case "$(jq -r .status <<<"$build")" in
              ready) echo "Built. It is published once its malware scan is clean (and a moderator has reviewed a first version)."; exit 0 ;;
              failed) jq . <<<"$build"; exit 1 ;;
            esac
            sleep 10
          done
          echo "::notice::Still building after 10 minutes: see the guide's Versions tab in the studio."
```

4. **Tag a release.** Raise `"version"` in pack.json, commit, then tag that
   version; the tag's message becomes the release notes:

```sh title="Terminal"
git tag -a v1.2.0 -m "What changed in this version"
git push origin v1.2.0
```

- **The tag must match pack.json.** `v1.2.0` uploads only a pack.json that
  says `"version": "1.2.0"`; anything else is refused.
- **Only the source goes up:** `pack.json`, `legs.json` and `retired.json`,
  `LICENSE` and `README`, every `.guide` file and `.tga` or `.blp` picture,
  never `dist/`, `drafts/` or hidden folders. If pack.json isn't at the top of
  the repository, set `GUIDE_DIR` to its folder.
- **A refused upload fails the run**, with the reasons (file, line, message,
  hint) in its log, and so does a failed build; the run waits for the build
  and passes once it is ready. A version that would drop route ids players
  follow is refused too: upload that one from the studio, which asks you to
  confirm.
- The workflow uses only `actions/checkout`, pinned by commit, and `curl`. An
  account can publish at most 30 uploads an hour.

## Where to go next

| Page | What it answers |
|---|---|
| [Writing a community guide](https://polestar.guide/docs/authors/community-guides) | What you get, the steps from your first guide to publishing, and the checklist before you do |
| [Handbook](https://polestar.guide/docs/authors/handbook) | Setup on each system, a first community guide in 15 minutes, testing, publishing and updating, every problem and its fix |
| [Guide format cheatsheet](https://polestar.guide/docs/authors/cheatsheet) | Every header line, goal and condition on one page, each with a short example |
| [Guide format](https://polestar.guide/docs/authors/guide-format) | The `.guide` language in full, what the compiler fills in, validation and a cookbook |
| [Community guide format](https://polestar.guide/docs/authors/community-guide-format) | `pack.json`, the addon the compiler writes, the rules Polestar enforces, import strings and versioning |
| [Translating](https://polestar.guide/docs/authors/translating) | The locale files, the glossary and the `i18n` commands |
| [Writing guides with an AI agent](https://polestar.guide/docs/authors/agent-workflow) | The workflow an AI agent follows to write, fix and build a community guide's routes |

> **Note:**
> A community addon is made and supported by its author. Polestar does not
> ship, host or recommend any, and players report problems in one to its
> author.

---

Next page: [Writing a community guide](https://polestar.guide/docs/authors/community-guides.md) · Every docs page: https://polestar.guide/llms.txt · All docs in one file: https://polestar.guide/llms-full.txt