mirror of
https://github.com/nexu-io/open-design.git
synced 2026-09-20 06:15:06 +08:00
Joey-nexu
f1a0b60c6c
* chore: unify product name display to OpenDesign repo-wide Rename the user-facing product name from "Open Design" to "OpenDesign" across documentation, web/desktop UI strings, i18n locales, prompts, plugin/skill/design-system content, changelogs, and specs, matching the landing-page rename already in flight. Deliberately excluded so installed-app identity stays untouched: - packages/release PRODUCT_NAME and everything derived from it (app bundle names, installer/registry identity, updater feeds) - tools/pack, tools/release, apps/packaged, landing page (PR #6983) - mocks/ recorded traces and LICENSE - test fixtures and comments that encode real on-disk install paths (Open Design.app, Program Files\Open Design, AppData paths) Validated with pnpm guard, pnpm typecheck, and targeted web/desktop/host test runs over the renamed strings. * fix(web): keep two-letter author monogram for CamelCase brand names authorInitials split words on whitespace only, so the renamed single-token author name "OpenDesign" produced a one-letter monogram. Treat lower-to-upper CamelCase boundaries as word breaks so the avatar fallback stays "OD". * fix(release): restore spaced Windows source artifact names in win.ps1 tools/pack still derives builder outputs from the unchanged PRODUCT_NAME ("Open Design"), so the asset script must look for the spaced filenames. Matches the mac/mac-intel/linux asset scripts, which were already kept on the original names. --------- Co-authored-by: Joey <236967869+joeylee12629-star@users.noreply.github.com>
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# Codex pets
|
|
|
|
The pet companion in the web app can adopt pets packaged by the upstream
|
|
Codex `hatch-pet` skill. This doc explains where those pets live, how
|
|
OpenDesign discovers them, and what to do if you do not have Codex
|
|
installed.
|
|
|
|
## Where pets live
|
|
|
|
The daemon scans this directory on every list request:
|
|
|
|
```
|
|
${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>/
|
|
pet.json # { id, displayName, description, spritesheetPath }
|
|
spritesheet.webp # 1536x1872 8x9 atlas (.png / .gif also accepted)
|
|
```
|
|
|
|
`CODEX_HOME` is honoured if set; otherwise the daemon falls back to
|
|
`~/.codex/pets/`. Both paths follow the upstream Codex conventions.
|
|
|
|
The scan is implemented in `apps/daemon/src/codex-pets.ts` and surfaced
|
|
through `GET /api/codex-pets` (list) and
|
|
`GET /api/codex-pets/:id/spritesheet` (raw bytes). The web pet settings
|
|
panel calls these endpoints from
|
|
`apps/web/src/components/pet/PetSettings.tsx` under the
|
|
"Recently hatched" section.
|
|
|
|
## I do not have Codex installed
|
|
|
|
You do not need Codex to use OpenDesign. The pet companion ships with
|
|
built-in pets that work out of the box. The "Recently hatched" section
|
|
will simply stay empty until something appears under
|
|
`${CODEX_HOME:-$HOME/.codex}/pets/`.
|
|
|
|
You have three ways to populate it without running Codex:
|
|
|
|
1. **Sync the public catalogs.** Run
|
|
`node --experimental-strip-types scripts/sync-community-pets.ts`
|
|
(see the script header for flags). It downloads pets from the
|
|
community catalogs into the canonical Codex layout, then they show
|
|
up under "Recently hatched" on the next refresh.
|
|
2. **Drop a pet folder in by hand.** Create
|
|
`~/.codex/pets/<your-pet>/` with a `pet.json` and a
|
|
`spritesheet.webp` (8x9 atlas). The daemon does not require Codex to
|
|
be installed — it only needs the directory.
|
|
3. **Run the vendored skill in any chat agent.** The `hatch-pet` skill
|
|
is vendored under `skills/hatch-pet/`. Any agent that can execute
|
|
skills (Codex, or any other) can run it end-to-end and write into the
|
|
same directory.
|
|
|
|
If `~/.codex/pets/` does not exist, the daemon does **not** auto-create
|
|
it — empty list is returned and the UI shows "no recently hatched pets
|
|
yet". Creating the directory is intentionally an explicit user step so
|
|
the daemon does not write into external tool homes without a user opting in.
|
|
Before documenting daemon-owned write paths, you MUST read root `AGENTS.md` →
|
|
**Daemon data directory contract**; this guide MUST NOT restate it.
|
|
|
|
## Manifest shape
|
|
|
|
The `pet.json` manifest is read defensively — every field is treated as
|
|
optional and validated as a string before use. The shape we honour:
|
|
|
|
```json
|
|
{
|
|
"id": "shiba-pomegranate",
|
|
"displayName": "Shiba Pom",
|
|
"description": "Friendly pixel-art shiba.",
|
|
"spritesheetPath": "spritesheet.webp"
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
|
|
- The folder name is the on-disk identity. The list endpoint reports
|
|
the sanitised folder name as the public `id` so that
|
|
`/api/codex-pets/:id/spritesheet` can resolve it directly even when
|
|
`manifest.id` differs from the folder name (e.g. the manifest declares
|
|
spaces or punctuation that get sanitised away).
|
|
- `spritesheetPath` is resolved relative to the pet folder and is
|
|
rejected if it would escape the folder. If unset, we fall back to
|
|
`spritesheet.webp`, then `.png`, then `.gif`.
|
|
- Any field that is not a non-empty string is ignored and the UI falls
|
|
back to a sensible default (folder name → display name, empty
|
|
description, etc.).
|
|
|
|
## Related code
|
|
|
|
- Daemon registry + manifest validation: `apps/daemon/src/codex-pets.ts`
|
|
- HTTP routes (list + spritesheet): `apps/daemon/src/server.ts`
|
|
- Web list / adopt UI: `apps/web/src/components/pet/PetSettings.tsx`
|
|
- Shared response types: `packages/contracts/src/api/registry.ts`
|
|
- Vendored skill source: `skills/hatch-pet/`
|
|
- Community catalog sync script: `scripts/sync-community-pets.ts`
|