# Set up radprofiles: instructions for AI agents

You are helping someone publish a radprofiles page: a public profile for their
Radicle identity (repositories, activity calendar, recent commits), read from
their own Radicle node. Work through the steps in order and check each one
before moving on. Commands are for macOS and Linux.

Project: `rad:z2v11Gpk44QqZ7zy8W9fva8wXXDBi` · Example: https://cstampar.radprofile.xyz

Tip: for working in Radicle repos afterwards (patches, issues, seeding), the
community Radicle agent skill for Claude Code is at
https://radicle.network/nodes/iris.radicle.network/rad%3AzvBj4kByGeQSrSy2c4H7fyK42cS8.
It isn't needed for this setup.

## Ground rules

- Ask before installing software, and before making anything reachable from
  the internet.
- Never create, read, or type the user's Radicle passphrase or private keys.
  If an identity has to be created, ask the user to run `rad auth` themselves.
- What appears on the profile is the user's choice: alias, bio, links, avatar,
  and which repositories to show. Suggest values, then confirm them.
- Only list public repositories. A private repository's name and commits must
  never end up on the page.
- `dashboard/.env.local` holds the configuration. It is gitignored; keep it
  that way.

## 1. Check prerequisites

```sh
node --version            # 20 or newer
git --version
rad --version
radicle-httpd --version
```

If `rad` or `radicle-httpd` is missing, Radicle isn't installed. With the
user's OK, run the official installer, which installs both into
`~/.radicle/bin` (add that to `PATH` if the installer says so):

```sh
curl -sSLf https://radicle.dev/install | sh
```

## 2. Confirm the Radicle identity

```sh
rad self --alias
rad self --did
```

Note both values. If these fail because there is no identity yet, stop and ask
the user to run `rad auth`, which asks them to pick an alias and a passphrase.

## 3. Start the node and its HTTP API

```sh
rad node status || rad node start
radicle-httpd --listen 127.0.0.1:8090
```

`radicle-httpd` runs in the foreground, so start it in the background or under
the user's process manager. Keep it on `127.0.0.1`: the site reads it locally,
and nothing outside the machine needs to reach it. Check that it answers:

```sh
curl -s http://127.0.0.1:8090/api/v1/node     # JSON with the node's "id"
```

## 4. Clone radprofiles and install

```sh
rad clone rad:z2v11Gpk44QqZ7zy8W9fva8wXXDBi
cd radprofiles/dashboard
npm ci
```

## 5. Check which repositories will show

By default the profile lists every public repository the user maintains. See
them with the DID from step 2:

```sh
curl -s "http://127.0.0.1:8090/api/v1/delegates/<DID>/repos?show=all"
```

Each item has a `rid`, a `visibility.type`, and a name at
`payloads["xyz.radicle.project"].data.name`; only `public` ones appear. Show
the user the names. If they want just some of them, list those RIDs in
`RADICLE_REPO_IDS` (step 6); otherwise leave it out.

## 6. Write the configuration

Create `dashboard/.env.local`:

```sh
RADICLE_HTTP_BASE=http://127.0.0.1:8090
SITE_MODE=personal
RADICLE_PROFILE_ALIAS=<alias from step 2>
RADICLE_DELEGATE_DID=<did from step 2>

# Optional. Ask the user before filling these in.
RADICLE_REPO_IDS=<only if they want a subset: rid,rid,rid>
RADICLE_PROFILE_BIO=<one line about what they build>
RADICLE_PROFILE_LINKS=site:https://example.com, email:mailto:you@example.com, x:https://x.com/handle
RADICLE_PROFILE_AVATAR_URL=<https URL, or a file in dashboard/public such as /avatar.png>
RADICLE_PINNED_REPOS=<up to six repo names or RIDs to feature first>
```

`dashboard/.env.example` documents every other setting.

## 7. Build, run, and check

```sh
npm run build
npm run start:personal        # serves http://localhost:3100
```

Check that `http://localhost:3100/profile` returns 200 and shows the user's
alias and the chosen repositories. If you can open a browser, look at it. To
keep the site running, use the process manager the user prefers (pm2, launchd,
or systemd) and ask which.

After any change to `.env.local`, run `npm run build` again and restart.

## 8. Publish (ask first)

Publishing makes the profile public, so let the user choose how:

- **Their own server:** a reverse proxy (Caddy or nginx) in front of port 3100.
- **A tunnel:** Cloudflare Tunnel or Tailscale Funnel pointing at port 3100.
- **Static hosting, no server:** export the data, then build a static site
  and upload `dashboard/out/` to any static host:

  ```sh
  npm run export-repos          # writes data/repos-snapshot.json
  npm run export-activity       # writes data/activity-snapshot.json
  # add to .env.local:
  #   RADICLE_ACTIVITY_SNAPSHOT_PATH=data/activity-snapshot.json
  #   SITE_URL=https://<where it will live>
  npm run build:static
  ```

  A static site only changes when you export and build again.

## 9. Hand over

Tell the user:

- the URL where the profile is served,
- which repositories it shows (new public repos appear on their own; to show
  only some, set `RADICLE_REPO_IDS` in `dashboard/.env.local`, then rebuild),
- how to update radprofiles later: `rad sync --fetch && git pull` in the
  `radprofiles` folder, then `npm ci`, `npm run build`, and a restart,
- that their Atom feed is at `/feed.xml` on the same site.