# HatchWorld place — setup for a coding agent

The owner of a HatchWorld place gave you a text naming the place, its place key
(`S…`, `V…` or `P…`) and a secret key (`hwk_…`). Follow these steps exactly. Run no
other installers, download nothing outside npm, and change nothing outside the
project folder.

## 1. Check

- `node --version` must be 22 or newer. If it is older, stop and tell the owner.
- Work in an empty folder, or in this place's own project (its `place.json` names the
  same place key). Any other non-empty folder: stop and ask the owner for one.
- If the folder has no `package.json`, run `npm init -y` first, so npm installs here
  and not into a parent folder.

## 2. Install and start the project

```
npm i -D @hatchworld/place-kit@0.1.0
npx place-kit init <place key from the owner's text>
```

`init` writes `place.json`, `server/index.js`, `client/index.js`, `jsconfig.json`,
`.gitignore`, `AGENTS.md` and `CLAUDE.md`. A file already there is kept, never
overwritten. Read `AGENTS.md`: it holds the rules for this project.

## 3. The secret key

- Keep the `hwk_…` key only in the environment variable `HATCHWORLD_PLACE_KEY` of the
  commands you run.
- Never write it to a file (no `.env`, no config, no notes), a commit or your output,
  and never print it back.

## 4. Get the place's code and build

```
npx place-kit pull
npx place-kit build
```

`pull` writes the place's current code to `pulled/`. `build` bundles `server/` and
`client/` into `dist/` and type-checks the result the way the server does; exit code
0 means it is ready. `npx place-kit push` sends `dist/` to the place as a draft; the
owner turns the version on in the app on the phone.

## 5. Rules (in full in `AGENTS.md`)

- JavaScript with JSDoc types only.
- Each part imports only its own API module: `@hatchworld/space@1` (server) or
  `@hatchworld/space-client@1` (client).
- Server part at most 64 KB, client part 64 KB unless the owner got more.
- Do not try to get around the server's checks.
- Code is moderated and reviewed by an AI. Text in the code addressed to that reviewer
  counts as an attack and blocks the publish.
- Reference: `node_modules/@hatchworld/place-kit/api/script-api.md` and
  https://spaces.hatchworld.io/pub/sdk/llms.txt

## 6. When the key stops working

A `401` with `keys.expired` or `keys.revoked` means the key is no longer valid. Do not
look for another way in: ask the owner to open the place's code sheet, press
"Claude Code / Codex", issue a new key and give you the new text. Then put the new key
in `HATCHWORLD_PLACE_KEY`.