Setting Beacon up for someone

This skill lives at .claude/skills/beacon-setup/ inside the Beacon
repository — a clone of it, or the copy this plugin installed. Two
directories up from this file is the repository root, and everything you
need is there: docs/ (the public documentation, which is the source of
truth for every step below), Scripts/, Triage/, Inbox/index.html and
the Swift package itself. Find that root first:

BEACON="$(cd "$(dirname "<path to this SKILL.md>")/../../.." && pwd)"
ls "$BEACON/docs"

Read docs/README.md there before anything else. The steps below say what
order to do things in and what to ask; the pages under docs/ say how, and
they win wherever the two seem to differ.

1. Find out which path

Ask, in one message, unless the answer is already clear from what they said:

• Do they track work in GitHub? No GitHub → the Claude-only path
  (docs/setup-claude-only.md): reports go to a page they own, and its dashboard
  is the whole tracker. Yes → ask who reports. Developers or a team with
  GitHub accounts → the GitHub path (docs/setup-github.md): reporters
  sign in with GitHub, reports become labelled issues, and the page is
  optional. The app's users, with no GitHub account → the relay
  (docs/setup-relay.md): reporters stay anonymous and never see GitHub,
  and a relay the owner runs files the issues.
• Which app, where is its source, and which platform (macOS, iOS, both)?
• Where should they be told when something happened? A Slack channel
  through a connector, an email, or nowhere.

Do not ask for anything the documentation does not need.

2. Do the path, in the documentation's order

Follow the numbered steps of the chosen setup page exactly. In outline:

Claude-only path

1. Publish Inbox/index.html from the repository root as an artifact with
   the db and artifact capabilities and the favicon 🎇. Load the
   artifact-capabilities skill first if it is available. The link it gives
   back is their Beacon page; tell them to keep it.
2. Have them open the page link and add each app in the page's Apps
   view (Add your first app on an empty page): name, platform, folder,
   and On this page for where reports are worked. If they would rather
   you did it, write one apps/<id> document per app with name,
   platform, folder and tracker: "board".
3. Put the button in the app (docs/quickstart.md, steps 1 to 3).
4. Set up the pickup (below).

GitHub path

1. Run Scripts/beacon-adopt-github.sh <app checkout> <owner/repo> from the
   repository root. It needs gh signed in. Commit what it copied.
2. Tell them to register a GitHub OAuth App with Device Flow enabled
   (docs/setup-github.md, step 2). That is theirs to do — it is a
   sign-in on their account. Ask for the Client ID when they have it.
3. Configure the app (docs/setup-github.md, step 4, and
   docs/quickstart.md).
4. Optionally publish the page and board, with each app's tracker set to
   github (the Claude-only path's steps 1 and 2).
5. Set up the pickup (below).

Relay

1. Run the adoption script as on the GitHub path, step 1.
2. Tell them to create and install the GitHub App, and to deploy the relay
   to Supabase with its secrets (docs/setup-relay.md, steps 1 to 3).
   Those are theirs to do — sign-ins, a private key and infrastructure on
   their accounts. Ask for the relay's address and the app token when they
   have them.
3. Configure the app (docs/setup-relay.md, step 4).
4. Set up the pickup (below).

The pickup, any path. Copy the prompt from Triage/PICKUP.md, fill in
its four values (their page link, the path to this repository, the folder
their code lives under, and where to notify), and offer it as a scheduled
task in Claude Code, daily, or as a prompt they paste when they want a run.
The pickup needs gh signed in to their GitHub account and python3 on the
Mac that runs it: it runs Scripts/mirror-board.py (the dashboard follows the
issues) and Scripts/push-edits.py (what they change on the dashboard reaches
the issues at the next run, because the page cannot call GitHub). Tell them
that, and that "Run now" on the task applies a change at once. On the
GitHub path there is also the copied workflow, which needs the Claude GitHub
App and one secret — both theirs to add; say so and point at the setup page.

The worker, any path. Copy the prompt from Triage/WORKER.md, fill in the
same values, and offer it as a second scheduled task in Claude Code: hourly,
permission mode Auto. The pickup triages and fills To do; the worker builds
what is in To do and flags a report Blocked (with a comment on the issue)
when it cannot finish. Ask before creating either task.

3. Prove it

Build the app, press the button, send a test report, and show them where it
landed: the dashboard at their page link (it opens there), or the issue in
their repository. A setup that has not filed one report is not finished.

Never

• Create, change or delete anything on an account they did not ask you to
  touch: no OAuth Apps, no repository secrets, no GitHub App installs, no
  scheduled tasks they have not agreed to. Say what is theirs to do and stop.
• Enter a token, secret or password anywhere. The Client ID is public by
  design and is the only value you handle.
• Edit a published page by hand. Inbox/index.html is the one home;
  republish from it.
• Skip the test report.