---
name: publik-setup
description: Set up the app in this repo on publik (publikhq.com) end to end. Read what it needs, list it, wire publik API where publik covers a need, and prove the wiring with a call made by the built app. Use when asked to "set up my app on publik". Change and publish nothing before the human says yes to the step 2 plan.
---

# Set up this app on publik

Read this file raw (curl), not through a summarising fetch; the shell blocks must run exactly as written.

This needs an interactive session: the human approves in the browser mid-run. In a non-interactive run (`claude -p`, `codex exec`), at each wait print what the human needs (checklist, or URL and code), stop, and tell them to re-run once they have answered.

You coordinate the whole setup. The human has https://publikhq.com/submit open: it shows each step as it lands and moves to the published screen when you are done, so nothing is typed there. Two other skills hold the commands, https://publikhq.com/skills/publish.md and https://publikhq.com/skills/api.md; fetch each raw with curl when its step comes.

**Rules.** Never read `.env*` files or print a secret (`pat_`, `pk_`, `pbt_`). Use what you can reach yourself. When you need something you cannot reach (a signing identity, a private dependency, a machine with another OS), say exactly what and why, then wait. Where the repo does not answer a question, ask it; do not guess.

## 1. Read the repo
Work out from the source and the manifests (key NAMES in `.env.example` only, never values):
- what the app is, how a release is built, and what a release produces (dmg, exe, AppImage, a CLI, a local web app);
- every outside service it calls. Mark each one publik covers: AI chat & tools (`ai.chat`), embeddings (`ai.embeddings`), speech to text (`ai.transcribe`), text to speech (`ai.speech`), image generation (`ai.image`), web search (`search`: plagiarism checks, citations, lookups).

An app that needs a covered service runs on publik API (`https://publikhq.com/api/v1`). That is required for its listing; the app's own-key path stays as the fallback.

## 2. One plan, one yes
Run publish.md steps 1 and 2 to derive the listing (a private repository: its step 1 says how to connect it first). Then show the human ONE checklist:
- the listing fields publish.md step 3 names, with every guess marked;
- what the app needs, and which of it publik API will provide. If the derived `publikApi.products` misses a covered need you found, add it and set `publikApi.enabled` to `true`;
- when publik API is needed: the plan of api.md step 1;
- the built-app test of step 6, with the command you will build with;
- what you need from the human: one approval in the browser, plus anything from the rules above.

**Print it, then stop and wait for a yes.** That yes also answers publish.md step 3 and api.md step 1. Change, run and publish nothing before it.

## 3. Approve once
Run publish.md step 4. The approval lasts one hour and covers every step below. Keep the work dir.

## 4. List it
Run publish.md step 5, but do not remove the work dir. Keep the `slug`.
- `held_for_review`: go on; the listing goes live once it is cleared.
- `409 repo_already_listed`: it is listed already. Use the returned `slug` and go on.

Stop here when the app needs nothing publik covers: go to step 7.

## 5. Wire publik API
Follow api.md steps 2 to 5 for `<slug>`, with the same work dir. In its step 2, skip the two device blocks: `$D/pbt.hdr` from step 3 is still good, so run only the mint block. Add the startup self-test its step 3 names.
- `403 claim_first`: the listing is in the repo author's name. The human opens the listing page and presses "Claim it with GitHub"; then run the mint block again.

## 6. Prove it from the built app
The proof publik counts is a call the app makes itself, built the way a release is built. Not the dev server, not a script that imports the module, not your own curl.
1. Build the release artifact with the project's own release command.
2. Run the built binary with the self-test switch and read the one line it prints:
```sh
PUBLIK_SELF_TEST=1 "<path to the built binary>"
```
macOS app bundle: `<App>.app/Contents/MacOS/<App>`. Windows: `set PUBLIK_SELF_TEST=1` and then `<App>.exe`. A CLI or a local web app: its normal start command.
- `publik self-test: ok <slug> <version>`: done; publik has recorded that build.
- `publik self-test: failed: <message>`: fix what the message names and run it again, twice at most. Then stop and show the human the line.
- no line: the self-test is not on the built app's startup path. Fix that and rebuild.

If a release build is not possible on this machine, say what is missing and ask. Only when the human agrees, run the app from source with the same switch, and say plainly that the release artifact was not tested.

## 7. Hand over
Tell the human in a few lines: the listing URL and its state; what publik API provides for the app; the self-test line; and what is left for them (commit, then tag a release so users get the wired build; publik picks up a new release within a day). https://publikhq.com/submit shows the same result. Then `rm -rf <work dir>`.