# Trap 2. GitW3, click by click — registration first, certification last

This file is a script for the **agent** to lead a **person** through. The person may never
have used git and does not have to start now. So the roles are split hard:

| Who | Does what |
|---|---|
| **Agent** | everything in a terminal: `git`, tags, pushing code. Silently, without explaining internals |
| **Person** | everything in a browser: clicks buttons, approves in the wallet |

Button labels are taken from the GitW3 documentation as of 2026-09-26. If something on the
person's screen is named differently, **what they see wins**: check
https://docs.w3ds.metastate.foundation/docs/GitW3/overview and lead by the actual interface,
not by this file. Ask them to read the button's text out loud.

One rule for the whole script: **one action at a time.** Say where to click → wait for
"clicked, I see this" → then the next step. A person cannot hold a seven-item list, and when
they go wrong on item three neither of you will know where.

---

## The two halves of this file, and why the order matters

**Part A — now, before any code exists.** Sign in, get the agent push access, create the
platform repository, clone it. Fifteen minutes. This is where the application gets its
permanent name in W3DS, and doing it first means every later commit lands in the right place.

**Part B — later, after the application actually runs at a real public address.** Publish a
release, get the PPA certificate for that exact version, register the deployment and its key.

Do not attempt Part B early. The certificate checklist requires a **public application URL**
and a **published stable release**; applying before those exist wastes a wallet signature and
teaches the person that the process is unreliable.

---

## What GitW3 is, and why not GitHub

An application in W3DS needs a **name** — a permanent platform eName, by which eVaults know
who is knocking. That name is issued not by a hosting provider and not by a domain, but by
GitW3: a code repository that additionally does three things GitHub and GitLab cannot:

1. issue the application a permanent **platform eName** (and provision its platform eVault —
   with no application key; see `traps/01-access-model.md`);
2. **certify one exact version** (PPA) — attest that this specific code was reviewed;
3. record a **deployment** — that this version is running there.

Without it the application stays a private experiment.

**Say this to the person, in one sentence:** "We're about to register your application so it
gets its own name in W3DS. Think of it as a passport — the code will come later, first there
has to be a record of it."

## What the person needs

- a phone with the eID wallet (the same one they sign into applications with);
- a computer with a browser.

Nothing else. No account, no password: there is no password in GitW3 at all.

---

# PART A — registration, before the first line of code

# Step 1. Sign in to the site

**Say this to the person, literally:**

> Open `git.w3ds.metastate.foundation` in your browser.
> There's a button that says **Sign in with W3DS** — click it.

Then two cases, and they have to tell you which is theirs:

- **On a computer:** a QR code appears. Open the wallet on the phone and scan it.
- **On a phone:** next to the QR there is an **Open your wallet** button — tap that.

> The wallet will show a sign-in request — approve it.
> **And do not close the browser tab** until the page moves you inside by itself.

That last sentence matters: a closed tab means the sign-in never completed, and it looks
exactly like a broken site.

**Step check:** the person says they can see their own name or icon in the top right corner.

**If the QR stopped working** — it is short-lived. Reload the page and start again. That is
normal behaviour, not an error.

---

# Step 2. A key so the agent can push code

## Warn them in advance, or they will think everything broke

**Signing in to the site and being allowed to push code are two different things.** The
wallet let the person into the website, but when the agent tries to push code there, it will
be asked for a login and password that do not exist. This is the most confusing spot in the
whole script and it catches everyone.

A **separate key** is needed. Two paths; take the first.

## Path A (recommended): an SSH key

**The agent does this, in a terminal.** First check whether a key already exists:

```bash
cat ~/.ssh/id_ed25519.pub
```

If there is no such file, create one:

```bash
ssh-keygen -t ed25519 -C "w3ds" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub
```

You get a single line starting `ssh-ed25519 AAAA…`. Hand **that line and only that line** to
the person — it is the public half and is safe to show. The file without `.pub` is never
shown to anyone, ever.

**Say to the person:**

> I'm going to give you a line of text to paste into the site.
> 1. Click your icon in the top right → **Settings**.
> 2. In the left-hand menu find **SSH / GPG Keys**.
> 3. Click **Add Key**.
> 4. In **Key Name** put anything, for example `my computer`.
> 5. Paste the line I'm about to send into the big **Content** box.
> 6. Click **Add Key**.

Then send the line as its own message, whole, with no line breaks.

**Step check (the agent does this):**

```bash
ssh -T git@git.w3ds.metastate.foundation
```

A reply along the lines of "Hi &lt;name&gt;! You've successfully authenticated" means the path
is open.

## Path B: a token (if SSH did not work out)

**Say to the person:**

> 1. Icon in the top right → **Settings**.
> 2. On the left — **Applications**.
> 3. Find **Generate New Token**, give it a name such as `for development`.
> 4. Create it and **copy the string it shows — it is shown only once**.

Then the important part:

> **Do not send that string to me in chat.** It works like a password. When you are asked for
> a password while code is being pushed, you'll paste it yourself.

Agent: you do not request the person's token, do not store it, and do not put it in commands.
If they send it anyway, say so plainly and ask them to revoke it and create a new one.

---

# Step 3. Create the platform

**Say to the person, one item at a time:**

> At the top of the page there's a **+** button. Click it → in the menu choose
> **New repository**.

> You'll be offered two options. We want **Make a new platform**. The other one
> (*Port an existing app*) is for moving applications that already exist — not ours.

If the person **does** already have an application with a W3DS identity, stop this script and
switch to the guided port flow: https://docs.w3ds.metastate.foundation/docs/GitW3/port-an-existing-application
A generic code import is not the same thing, and using it can strand an existing eName.

## Screen 1 — Repository

> 1. **Owner** — leave yourself (your name is already there).
> 2. The "private" checkbox — leave it on and the code is visible only to you. Fine for now.
> 3. **Display name** — **the application's name in human words**, for example
>    `Contract register`. People will see this.
> 4. Default branch — leave `main`, change nothing.
> 5. Click next.

**Say this separately, so they don't hunt for a field:** they do **not** choose the short
technical name. GitW3 derives it from the display name. And that derived name **never
changes** afterwards, even if the display name does — so the name is worth thinking about now.

## Screen 2 — Platform details

> 1. **Description** — one or two sentences on what the application does.
> 2. **Application domains** — pick one or more areas from the list. Pick at least one:
>    without it, no certificate later.
> 3. **Application URL** — the application's public address. If it already exists, type it.
>    If not, leave it empty and come back here later.
> 4. **Logo URL** — optional, skip it.

There is no "version" field on this screen and there should not be: the version comes from
releases, never typed by hand. The manifest starts at `0.1.0`.

**On domains, say something true rather than something reassuring.** The domains chosen here
are what the release can later be certified for, and the certificate cannot be widened
afterwards by anything — not by the data owner's own permission. So if the application will
ever touch health or financial records, that has to be said now, not discovered later.

## Screen 3 — AI setup

> This screen just offers a command for setting up an AI assistant.
> Nothing to fill in — click next.

> And the last button: **Create platform**.

The command it offers is the official W3DS skill, and the agent should run it regardless:

```bash
npx skills add MetaState-Prototype-Project/prototype@w3ds
```

## After creation

The person sees the created repository. **The platform eName does not appear immediately** —
it is issued in the background.

**Say:**

> There are tabs at the top of the page. Find the **W3DS** tab and open it.
> It shows the status — your application's name will appear there within a few minutes.
> If it's still empty, just reload the page in a minute.

**Do not let the person conclude something broke.** Tell them in advance: "the name appears
with a delay, that's normal."

**Step check:** the person reads the platform eName out loud from the **W3DS** tab. Write it
down — it is the application's permanent identity, and it also sits in
`.w3ds/platform.json` as the `ename` field.

---

# Step 4. The agent takes the repository over

**Entirely the agent's work.** Report only the result to the person.

Ask them to click the **SSH** clone control on the repository page and send you the string.

**Important:** the `@` before a name on the site is decoration and is **not part of** the
address. Copy the address exactly as shown, adding and removing nothing.

The repository already contains a README and `.w3ds/platform.json`, so **clone it rather than
creating a new repository locally** — a fresh `git init` plus a force-push is how the manifest
GitW3 just wrote gets destroyed:

```bash
git clone <address from the SSH control>
cd <repository directory>
cat .w3ds/platform.json          # read it; do not edit the managed fields
```

Read the manifest and treat these fields as not yours to touch: `schemaVersion`,
`platformName`, an assigned `ename`, the release-controlled `version`, and any signed proof
fields. Everything else — `displayName`, `description`, `domains`, `url`, `logoUrl` — can be
edited, but prefer editing it through the **W3DS** tab, and remember that saving there makes
a commit, so `git pull` afterwards.

Now build the application **inside this checkout**, and before the first push make sure no
secrets are in it:

```bash
cat >> .gitignore <<'GIT'
.env
.env.*
*.pem
w3ds-deployment-key.json
GIT
```

A pushed secret counts as compromised even if the next commit removes it.

Day-to-day pushing, once there is something to push:

```bash
git add <files>
git commit -m "feat: describe the change"
git push
```

**Say to the person:**

> Your code is up. Reload the repository page — you should see the project's files there.

**Step check:** the person sees their project's files on the repository page.

---

## Part A is done when

- [ ] the person sees their own icon in the corner of the site (signed in);
- [ ] `ssh -T git@git.w3ds.metastate.foundation` authenticates (or the token path works);
- [ ] the **W3DS** tab shows a platform eName;
- [ ] the agent has the repository cloned, with `.w3ds/platform.json` intact;
- [ ] the person sees their project's files in the repository.

Now go and build the application: `traps/03-public-address.md` next. Come back here for
Part B when the application runs at a real public address.

---

# PART B — later: release, certificate, deployment

Do not start this until the application actually works at a permanent public address and the
person has signed in to it with their own eID, both ways (see `traps/04-eid-login.md`).

# Step 5. The application's public URL

If the URL was left blank on screen 2, now is the time — **without it no certificate**.

**Say:**

> Open the **W3DS** tab in your repository, put the application's public address into the
> **Application URL** field, and save.

Warn them: saving from that tab is a change to the code (GitW3 makes the commit itself). The
agent should `git pull` afterwards, or you end up with competing manifest edits.

---

# Step 6. Publish a version

What gets certified is not the application in general but **one exact version**. So the
version has to be declared.

**The agent does this:**

```bash
git switch main
git pull --ff-only
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
```

Three numbers separated by dots. The first version is usually `v0.1.0`.

**Say to the person:**

> 1. In your repository open the **Releases** tab.
> 2. Click **New release**.
> 3. In the tag selector choose **v0.1.0** — I just created it.
> 4. Below, you can write a couple of words about this version. Or skip it.
> 5. **Do not tick any checkbox** — not "draft", not "pre-release".
>    We need an ordinary, final release.
> 6. Click publish.

Item 5 is where this script breaks: a draft or a pre-release does **not** become the platform
version, and in the interface it looks exactly the same. Say so explicitly.

**Step check:**

> Go back to the **W3DS** tab. Within a minute version `0.1.0` should appear there.

(The `v` in the tag is dropped — that is correct, not a bug.)

---

# Step 7. The PPA certificate

## Walk the checklist together first

The **W3DS** tab has a **PPA certificate** section with a list of conditions. Ask the person
to read it out loud, item by item. All of it must be satisfied:

- the platform eName has been issued;
- at least one application domain is chosen;
- the public application URL is filled in;
- an ordinary (not draft) release with a version like `0.1.0` is published;
- the person is signed in with their wallet and is an owner/admin of the repository.

If an item is not satisfied, **go back and close it** rather than trying to apply: the button
either will not work or the application will be rejected.

## Submitting

**Say to the person, and warn them there is a timer:**

> There'll be a wallet signature now, and you get **15 minutes** for it. Have your phone in
> your hand before you start.
>
> 1. Check that the version on screen is the right one, `0.1.0`.
> 2. Click **Sign and apply for PPA certificate**.
> 3. A QR code appears — scan it with the wallet. On a phone the wallet opens by itself.
> 4. In the wallet, read what you are signing, and approve it.
> 5. **Do not close the browser window** until the site says the signature was accepted.

Repeat item 5 twice. Having approved on the phone, a person instinctively closes the tab —
and the signature never lands.

## What happens next

The application goes to human review. The states the person will see:

| On screen | What it means |
|---|---|
| **Ready to apply** | everything is in place, you can submit |
| **Application submitted** | signed, waiting in the review queue |
| **PPA certificate granted** | granted — go on to step 8 |
| **PPA application denied** | refused, with a reason |

**Tell the person plainly: time passes between "submitted" and "granted", and that is not a
fault of yours.** Do not leave them staring at the screen.

On a refusal: the same tab takes a short response — what changed, or why the version should be
reconsidered — and then **Sign and reapply**, with a fresh wallet signature.

**And the thing everyone forgets:** the certificate is granted for `0.1.0` and **only** for
`0.1.0`. Ship `0.1.1` and steps 6 and 7 are done again from the start. This is not
bureaucracy, it is the whole meaning of the certificate: it attests to specific code, not to
a name.

---

# Step 8. The deployment record and its key

This step applies once the application is genuinely running somewhere. GitW3 **does not host**
anything — it only records that such-and-such version is run by such-and-such people.

**Say to the person:**

> 1. Open the **Deploy** tab.
> 2. **Step 1** — choose a release. Only versions with a granted certificate are listed.
> 3. **Step 2** — give the deployment a readable name, for example `production`, and choose
>    the environment: **Production**, **Staging**, **Development** or **Custom**.
> 4. **Step 3** — choose **Generate a deployment key**.

Then the most consequential moment in the whole script:

> The browser **downloads a file called `w3ds-deployment-key.json`**. It is downloaded
> **once**. It cannot be recovered — not through the site, not through support, not at all.
>
> Find it in your downloads folder and move it to wherever you keep important things.
> **Do not send me this file. Do not open it in chat. Do not upload it anywhere.**

> 5. **Step 4** — check that the version, name and environment on screen are right, and click
>    **Create identities and continue to wallet**.
> 6. Sign in the wallet again — one signature covers both records.
> 7. Wait until the deployment card reaches the published state.

GitW3 reserves two identities here: a **deployment eName** bound to the public key and the
connected deployer, and a **software-version eName** bound to the platform eName, the release
version and the exact commit. Nothing is provisioned until the signature verifies.

If the runtime or a secret manager already holds a compatible W3DS P-256 key, the other path
is **Use an existing public key** — paste only the `z`-prefixed public key. Never paste a
private key into GitW3.

## Hard rules for the agent about that file

- **Never ask for it.** If the person sends it anyway, tell them it must be treated as
  compromised and a new deployment issued.
- **Never commit it**, and do not put it in the project directory: `w3ds-deployment-key.json`
  went into `.gitignore` back in step 4.
- On the server it is wired in **by path**, not by content:
  `W3DS_DEPLOYMENT_KEY_FILE=/path/to/file`, pointing at a read-only mount or a secret
  manager's file.
- Only server code may read it. It never reaches the frontend.
- Validate it at startup: P-256/SHA-256, and the private key must derive the expected public
  key. Fail loudly if it does not.
- Lost means lost. A new deployment with a new key is the only recovery, rolled out
  deliberately: keep the old secret available for the rollback window, verify the new
  public-key match at startup, then destroy the old one.

What the key is *for* is in `traps/01-access-model.md`: it signs PP-Auth challenges. It is not
a bearer token, and PP-Auth SDK integration is marked coming soon — do not invent it.

---

# When something goes wrong

| What the person sees | What it actually is |
|---|---|
| QR didn't work / "expired" | the QR is short-lived — reload the page and start again |
| Approved in the wallet, browser didn't move | the tab was closed or left too early; retry with a fresh request |
| The agent is asked for a password when pushing | step 2 was skipped: site sign-in ≠ push access |
| The application's name never appeared | it is issued in the background — wait and reload the **W3DS** tab |
| The PPA button won't click | some checklist item is not closed — read the whole list |
| The version isn't in the Deploy tab's list | there is no certificate for **that** version |
| Release published but the version didn't appear | the release stayed a draft or a pre-release |
| An old name or avatar on the site | sign out and back in — the profile is pulled at sign-in |
| "Where do I get the API key?" | there is no such key — `traps/01-access-model.md` |

---

# A small glossary, if the person asks

- **Repository** — a folder of code that keeps the whole history of its changes.
- **Commit** — a saved state of the code with a note on what changed.
- **Branch (`main`)** — the main line of development.
- **Tag** — a label on one specific state of the code, like `v1.2.3`.
- **Release** — a declaration that this label is a finished version.
- **Push** — moving what was done on the computer into the repository on the site.
- **Platform eName** — the application's permanent name in W3DS.
- **PPA** — a certificate for one exact version.
- **Deployment** — a record that this version is running here.

---

# The check that closes this stage

Everything is done when the person sees, **with their own eyes**:

- [ ] their icon in the corner of the site (signed in);
- [ ] their project's files on the repository page;
- [ ] the platform eName on the **W3DS** tab;
- [ ] version `0.1.0` in the same place;
- [ ] the words **PPA certificate granted**;
- [ ] `w3ds-deployment-key.json` saved on their own machine — and nowhere else.

Do not tick a box on the person's behalf. "It's probably appeared by now" is not a check.
