From e5b46798844f63bc22b61352941df90bede5793f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=AE=87607?= <113445115+xiaoyu607@users.noreply.github.com> Date: Wed, 21 Oct 2026 09:36:20 +0700 Subject: [PATCH 1/4] docs: link Codex setup in generated README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dfae671..f81123e 100644 --- a/README.md +++ b/README.md @@ -213,7 +213,7 @@ It runs on your machine. The only things that leave it are the model calls the d ## Docs -[Commands](docs/commands.md), [the desks](docs/roles.md), [the dashboard](docs/dashboard.md), [cost](docs/cost.md), [the runner](docs/runner.md), [providers](docs/providers.md), [privacy](docs/privacy.md), [first contribution](docs/first-contribution.md). +[Commands](docs/commands.md), [Codex setup](docs/codex.md), [the desks](docs/roles.md), [the dashboard](docs/dashboard.md), [cost](docs/cost.md), [the runner](docs/runner.md), [providers](docs/providers.md), [privacy](docs/privacy.md), [first contribution](docs/first-contribution.md). To cite Desk Studio, use [CITATION.cff](CITATION.cff) or GitHub's **Cite this repository**. From 1e92ad2e148d1d2530acde8527ecb63ea3e29da5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=AE=87607?= <113445115+xiaoyu607@users.noreply.github.com> Date: Wed, 21 Oct 2026 09:37:14 +0700 Subject: [PATCH 2/4] docs: add Codex setup and repeat-install guide --- docs/codex.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/codex.md diff --git a/docs/codex.md b/docs/codex.md new file mode 100644 index 0000000..e378820 --- /dev/null +++ b/docs/codex.md @@ -0,0 +1,78 @@ +# Codex setup + +Add Desk Studio to an existing project without losing its instructions or edited desk briefs. + +## Install + +Use Node.js 20 or newer. Install Codex following the [official CLI setup](https://developers.openai.com/codex/cli), then check `codex --version`. For example, the official macOS/Linux installer is: + +```sh +curl -fsSL https://chatgpt.com/codex/install.sh | sh +``` + +From your project's root, run: + +```sh +npx deskstudio add --agent codex +``` + +This creates or updates `AGENTS.md`, copies the Manager's skill, role briefs, rubric, standards and procedures to `.agents/skills/desk/`, and seeds `.desk/project.json`, `.desk/taste.md` and `.desk/.gitignore` if missing. Installation makes no model calls and does not create `.desk/DESIGN.md`; a design job finds the brand in the project. + +Codex reads [project instructions from AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md) and discovers [local skills in .agents/skills](https://developers.openai.com/codex/build-skills). Start a new Codex session from the project root after installation so it loads the updated instructions: + +```sh +codex +``` + +Sign in using the official setup if needed. Then try this design request: + +```text +Use Desk Studio to improve this project's landing page. Read +.agents/skills/desk/SKILL.md, use the existing brand and components, +and check the result at phone and desktop sizes. +``` + +For work inside the codebase, Codex plays the Design Manager from the installed briefs. The separate runner currently supports `design` for a social card; see [command availability](commands.md#command-availability) before trying other commands. Design work uses models through your host or configured providers and may incur usage costs; installation and the check below do not need a model account. Visual proof needs Chrome or Chromium, and motion exports also need system `ffmpeg`; see [prerequisites](../CONTRIBUTING.md#run-the-checks). + +## What a second install keeps + +`AGENTS.md` contains a managed block between `` and ``. Every install refreshes that block, even without `--force`, while preserving text above and below it. If there is no block, the installer appends one. Put project-specific instructions outside the markers. + +| Content | Normal install | With `--force` | +| --- | --- | --- | +| Text outside the markers in `AGENTS.md` | Kept | Kept | +| Desk Studio block inside the markers | Refreshed | Refreshed | +| Existing files in `.agents/skills/desk/` that differ from the package, including edited briefs | Kept and reported as edited | Replaced with the package copy | +| Missing packaged skill files | Added | Added | +| Existing `.desk/` seed files | Kept | Kept | + +`--force` replaces differing packaged skill files, not just role briefs. It does not reset `.desk/project.json` or `.desk/taste.md`, write `.desk/DESIGN.md`, or delete extra user-created skill files. Back up edits before using it: + +```sh +npx deskstudio add --agent codex --force +``` + +## Try it in a disposable project + +These macOS/Linux shell commands check a second install without starting Codex or running a design job. Use the same Desk Studio version for both installs. + +```sh +mkdir -p /tmp/deskstudio-checks +project_dir=$(mktemp -d /tmp/deskstudio-checks/codex.XXXXXX) +cd "$project_dir" +printf '# Project instructions\n\nKeep this above the studio.\n' > AGENTS.md +npx deskstudio add --agent codex +printf '\nKeep this below the studio.\n' >> AGENTS.md +brief=.agents/skills/desk/roles/ui-designer.md +printf '\nProject-specific UI guidance.\n' >> "$brief" +cp AGENTS.md expected-AGENTS.md +cp "$brief" expected-brief.md + +npx deskstudio add --agent codex +cmp AGENTS.md expected-AGENTS.md +cmp "$brief" expected-brief.md +``` + +Both `cmp` commands should exit zero with no output. The second install should report `AGENTS.md: unchanged`, the seed files as `kept`, and `roles/ui-designer.md` as kept as edited. There should still be just one pair of Desk Studio markers. If the package adapter changes between versions, the block can change while your surrounding text stays intact. + +In this disposable project, you can also repeat with `--force`: the brief should return to the packaged version while the instructions outside the markers remain. These are installer checks, not evidence of a live Codex design session. From 51f8ea5009f6c17bc605292605bb1344c4aed1be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=AE=87607?= <113445115+xiaoyu607@users.noreply.github.com> Date: Wed, 21 Oct 2026 09:37:54 +0700 Subject: [PATCH 3/4] docs: add Codex guide link to README generator --- site/readme.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/readme.mjs b/site/readme.mjs index 77e7b65..3cfe077 100644 --- a/site/readme.mjs +++ b/site/readme.mjs @@ -230,7 +230,7 @@ It runs on your machine. The only things that leave it are the model calls the d ## Docs -[Commands](docs/commands.md), [the desks](docs/roles.md), [the dashboard](docs/dashboard.md), [cost](docs/cost.md), [the runner](docs/runner.md), [providers](docs/providers.md), [privacy](docs/privacy.md), [first contribution](docs/first-contribution.md). +[Commands](docs/commands.md), [Codex setup](docs/codex.md), [the desks](docs/roles.md), [the dashboard](docs/dashboard.md), [cost](docs/cost.md), [the runner](docs/runner.md), [providers](docs/providers.md), [privacy](docs/privacy.md), [first contribution](docs/first-contribution.md). To cite Desk Studio, use [CITATION.cff](CITATION.cff) or GitHub's **Cite this repository**. From 784172b634b73e018abd1f9130583887d39b5c73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=AE=87607?= <113445115+xiaoyu607@users.noreply.github.com> Date: Wed, 28 Oct 2026 01:01:14 +0700 Subject: [PATCH 4/4] docs: clarify Codex install upgrade and provider requirements --- docs/codex.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/codex.md b/docs/codex.md index e378820..ac34cd7 100644 --- a/docs/codex.md +++ b/docs/codex.md @@ -10,6 +10,8 @@ Use Node.js 20 or newer. Install Codex following the [official CLI setup](https: curl -fsSL https://chatgpt.com/codex/install.sh | sh ``` +Sign in using the official setup before adding Desk Studio. A fresh install needs a ready model provider; it stops before writing project files if none is available. Check provider access with `npx --package deskstudio desk-run doctor`, which makes no model call. + From your project's root, run: ```sh @@ -24,7 +26,7 @@ Codex reads [project instructions from AGENTS.md](https://developers.openai.com/ codex ``` -Sign in using the official setup if needed. Then try this design request: +Then try this design request: ```text Use Desk Studio to improve this project's landing page. Read @@ -32,7 +34,7 @@ Use Desk Studio to improve this project's landing page. Read and check the result at phone and desktop sizes. ``` -For work inside the codebase, Codex plays the Design Manager from the installed briefs. The separate runner currently supports `design` for a social card; see [command availability](commands.md#command-availability) before trying other commands. Design work uses models through your host or configured providers and may incur usage costs; installation and the check below do not need a model account. Visual proof needs Chrome or Chromium, and motion exports also need system `ffmpeg`; see [prerequisites](../CONTRIBUTING.md#run-the-checks). +For work inside the codebase, Codex plays the Design Manager from the installed briefs. The separate runner currently supports `design` for a social card; see [command availability](commands.md#command-availability) before trying other commands. Design work uses models through your host or configured providers and may incur usage costs; installation and the check below make no model calls, though a fresh install needs a detected provider. Visual proof needs Chrome or Chromium, and motion exports also need system `ffmpeg`; see [prerequisites](../CONTRIBUTING.md#run-the-checks). ## What a second install keeps @@ -42,10 +44,13 @@ For work inside the codebase, Codex plays the Design Manager from the installed | --- | --- | --- | | Text outside the markers in `AGENTS.md` | Kept | Kept | | Desk Studio block inside the markers | Refreshed | Refreshed | -| Existing files in `.agents/skills/desk/` that differ from the package, including edited briefs | Kept and reported as edited | Replaced with the package copy | +| Untouched skill files matching a recorded install hash or the recognized npm 1.0.0 baseline | Updated to the package copy | Updated to the package copy | +| Edited skill files or copies with no recognized baseline at packaged paths | Kept and reported as edited | Replaced with the package copy | | Missing packaged skill files | Added | Added | | Existing `.desk/` seed files | Kept | Kept | +The installer records packaged skill hashes in `.desk/installed.json`. It retains the previous baseline for preserved edits so a later install does not mistake them for untouched files. + `--force` replaces differing packaged skill files, not just role briefs. It does not reset `.desk/project.json` or `.desk/taste.md`, write `.desk/DESIGN.md`, or delete extra user-created skill files. Back up edits before using it: ```sh @@ -54,7 +59,7 @@ npx deskstudio add --agent codex --force ## Try it in a disposable project -These macOS/Linux shell commands check a second install without starting Codex or running a design job. Use the same Desk Studio version for both installs. +These macOS/Linux shell commands check a second install without starting Codex or running a design job. Use a machine with a provider already configured, and use the same Desk Studio version for both installs. ```sh mkdir -p /tmp/deskstudio-checks