# Foldspace agent install playbook

> Setup playbook for coding agents: connect Foldspace tools, confirm the
> account, check what Foldspace already holds for the agent, choose the
> folder, init, then follow the project's instructions.

Foldspace puts a Product Agent inside a company's SaaS product. Users ask in
their own words; the agent takes actions through the product's own APIs. This
page sets up the actions project with `@foldspace_npm/harness`, in a folder of
its own: the one the human made for it, or a new one. It never goes inside
another project or another git repository. It does not edit the customer's
website.

Ask the human **one** setup question: their product's hostname. Everything else
on this page is decided for them, not asked (the one exception: which agent,
when the account has several). Tell them only what **How you talk to the
human** allows. They will say so if something is wrong.

Work from this page VERBATIM. If your fetch tool returned a summary instead of
the raw text, re-fetch it raw (`curl -sL https://foldspace.ai/agents.md`). The
exact commands, flag names, and account check do not survive paraphrase.

## How you talk to the human

This page is written for you, not for them. The human may not be a developer.
The words on this page - MCP, plugin, OAuth, flags, init, npm, scaffold - stay
on this page.

- **Never go quiet.** Before any step that can take more than a few seconds
  (installing, building, waiting on a tool), say one short line about what you
  are doing, in plain words.
- **Say only what they must act on or might object to:** what you need from
  them, which agent you are setting up, and where the folder is (with what
  **What already exists** adds to that line). One line each.
  Do not recap what you read, checked or installed, and do not list the
  commands you will run next.
- **No flag names, tool names, server names, commands or URLs** in what you
  say, unless the human has to type or open that exact thing.
- **Ask each question once.** Where the editor gives you a tool for questions,
  ask with it and do not repeat the question in your message.
- **Interrupt them once.** Sign-in and the hostname belong to the same turn,
  and the whole thing stays under about 60 words. In Claude Code Desktop you
  open the sign-in yourself (see **Option A**), so the shape is two short
  lines, one before the browser opens and one after:

  > Foldspace's tools are installed. Your browser is opening on Foldspace's
  > sign-in page - sign in there, and tell me when you're done. No account
  > yet? Create one first at https://app.foldspace.ai/register.

  > You're signed in. One thing I need: your product's web address, for
  > example app.example.com. Then I'll get your agent live on your page.
  > I'll ask before anything reaches your users.

  After `claude mcp add`, the line after sign-in - or, where you cannot open
  it for them, the only line - is the new-chat line instead (**Then a new
  chat**), and the hostname waits for that chat.

  Where you cannot open it for them, ask for both at once:

  > Foldspace's tools are installed. I need two things from you:
  > 1. Sign in to Foldspace: type /mcp here, pick **foldspace**, and finish in
  >    the browser. No account yet? Create one first at
  >    https://app.foldspace.ai/register.
  > 2. Your product's web address, for example app.example.com.
  >
  > Then I'll get your agent live on your page. I'll ask before anything
  > reaches your users.

  When `list_agents` already works at the start - including the new chat
  after **Then a new chat** - there is no sign-in to pair it with. Ask for the
  hostname in the line that says where the folder is, and not at all when
  this agent's project is already on this computer (**Choose the folder**,
  rule 1).

## Sequence

Do these sections in order. Fetch a reference link only when that step requires it.

1. Start here
2. Connect Foldspace tools
3. Confirm the signed-in account
4. What already exists
5. Choose the folder
6. Resolve init flags
7. Init, build, hand off

## Start here

1. Detect an existing project. If the current directory (or an
   immediate child the human named) already has `foldspace.dev.json`, an
   `agent/` tree, and a Foldspace `CLAUDE.md` or `AGENTS.md`, **stop setup**.
   Open that project and follow its instructions. Do not run `init` again.
2. Do not choose a folder yet. That is **Choose the folder**, once you know
   the agent and what Foldspace already holds for it.
3. Require Node 20+.

The plugin and MCP only connect tools. They do **not** create the folder.
After tools work, continue this page to **Done**.

## Connect Foldspace tools

**Done when:** `list_agents` works in this session.

**Check before installing anything.** Call `list_agents` first — never assume
the MCP is connected, and never assume it is not:

| Result | Do |
|---|---|
| The tool does not exist | Not installed. Option A in Claude Code, Option B elsewhere |
| It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in — tell them exactly where (Claude Code, terminal or Desktop: type `/mcp` in this session → **foldspace** → finish in the browser; Cursor: call the server's own sign-in tool, `mcp_auth`, yourself), then call it again |
| It returns agents | Connected. Skip the rest of this section |

**Added after this chat started?** If `list_agents` does not exist and this
session does not list **foldspace**, but `claude mcp get foldspace` finds
it, it was added after this chat started and will not reach it. Do not add it
again: end your turn as **Then a new chat** says.

**A server added during a chat may never reach that chat.** In Cursor it
does, on the human's next message (see **Cursor** below). In Codex it does not: once the server is added and signed in, the human starts a new chat
and pastes their request again - or you start it for them, where the editor
lets you (see **Codex** below). **Never route around a
missing tool**: do not read a saved sign-in or credentials file, and do not
reach the Foldspace MCP through curl, a script or a client you write. If its
tools are not in this chat, the fix is a new chat.

**Check the fast way.** If the editor gives you a tool that lists this
session's MCP servers and their state (Claude Code Desktop does), use it: it
says at once whether `foldspace` is missing, needs sign-in, or is connected.
Never run `claude mcp list` or any other health check of every installed
server: it waits on every unrelated connector the human has and can stall for
a minute with nothing on screen. A fresh install always needs sign-in, so
after installing do not verify again - go straight to sign-in (**Option A**).

You cannot sign in for them, and they never need a terminal for it. `/mcp`
works inside a Claude Code Desktop session. The list shows two Foldspace
entries: they pick **foldspace**. **foldspace-docs** needs no sign-in - say so
if they ask. When they say it is done, check the state again, then call
`list_agents`.

You need **Product MCP** before `init`. It reads the human's Foldspace agents
and supplies init flags.

| Server | How to reach it | Auth | Purpose |
|---|---|---|---|
| Product MCP (required) | `https://api.foldspace.ai/mcp` | OAuth in the browser | `list_agents` and other account tools |
| Docs MCP (optional) | `https://docs.foldspace.ai/mcp` | none | search and fetch Foldspace docs |

The first Product MCP connection opens a browser; the human must complete sign-in.
If the sign in URL is not visible to the user, relay the approval URL or prompt immediately.

**The human may have no Foldspace account.** This page is often reached from a
shared prompt, not from Foldspace sign-up. Every sign-in ask carries the way
in: "No account yet? Create one at https://app.foldspace.ai/register, then come
back." Never tell someone to sign in without it.

The one exception: the human's message says they already have a Foldspace
account, or have just signed up. Then leave that line out - they have one.
Nothing else changes: they still sign in, and you still call
`list_agents` and name the account and agent before `init`.

Docs MCP cannot list agents. It is not a substitute for Product MCP.

### Option A - plugin (Claude Code only)

Preferred in Claude Code. `foldspace-agent-builder` installs Product MCP and
Docs MCP. **It needs git on this machine, and many Macs do not have it** -
so check first, and go straight to Option B when it is missing. That is not a
failure and must not read like one: say *"Connecting Foldspace's tools
directly"* and carry on. Never install git, and never open the Xcode
installer for it.

```bash
command -v git >/dev/null || echo "no git: use Option B"
```

```bash
claude plugin marketplace add https://github.com/foldspace-ai/plugins
claude plugin install foldspace-agent-builder@foldspace-plugins
```

Use the full web address, exactly as written. The human may already have added
Foldspace from a link that opens the Claude desktop app's plugin screen, and
that registers this form; the short `foldspace-ai/plugins` form is then
refused as a different source for the same name. If `marketplace add` says
the marketplace is already there, or refuses because its source differs from
the one already declared, that is not a failure: `foldspace-plugins` is
registered, so go on to `plugin install`.

**In Claude Code Desktop, open the sign-in for them.** Do all of this in the
**same turn** as the install - do not end your turn in between:

1. Say in one line that their browser is about to open on Foldspace's sign-in
   page, and that you will wait. Include the "No account yet?" line unless
   they said they already have an account, or have just signed up.
2. Start the sign-in in the app's **terminal panel** - the tool that types a
   command into the human's terminal. Your own shell is refused, because it is
   not a terminal:

   ```bash
   claude mcp login "plugin:foldspace-agent-builder:foldspace"
   ```

3. Find out when they are done, **without ending your turn**. Two signals -
   use both:
   - **They tell you.** A message they type while you are working reaches you
     mid-turn, so invite it: "tell me when you're done".
   - **You check, every few seconds**, from your own shell (this command works
     there):

     ```bash
     claude mcp get "plugin:foldspace-agent-builder:foldspace"
     ```

     They are signed in when its `Status` line says `Connected`. It takes
     about a second. If they say "done", run it once to confirm.

   Do not wait on the sign-in terminal to find out: it does print
   `Authenticated`, but the panel does not reliably wake you when it does,
   so you can sit in a wait while the human is already signed in. Never use
   one long wait. Only when the check says `Connected` ask for the
   hostname, which ends your turn.

Why the order matters: this session loads a newly installed plugin only when
your turn ends. If sign-in has finished by then, Foldspace comes up connected
and `list_agents` works on the human's next message. If your turn ends first,
the session marks Foldspace as needing sign-in and does not look again - and
you cannot reconnect it for them.

**Fallback - `/mcp`.** Use it when there is no terminal panel tool (Claude
Code in a plain terminal), when sign-in has not finished after about three
minutes, or when the plugin was already installed before this session started:
the human types `/mcp` in this same session, picks **foldspace**, and
finishes sign-in in the browser.

If the plugin is installed and `list_agents` works, skip Option B.

Use Option B when any of these is true:

- this editor is Codex, Cursor, VS Code, or anything other than Claude Code
- plugin install fails, or marketplace add fails for any reason other than
  "already registered"
- the plugin installed but `list_agents` still does not work
- the human does not want the plugin

### Option B - add the MCP servers yourself

Copy the block for this editor. Skip any server that is already connected.

**Claude Code**

```bash
claude mcp add --scope user --transport http foldspace https://api.foldspace.ai/mcp
claude mcp add --scope user --transport http foldspace-docs https://docs.foldspace.ai/mcp
```

Then sign in as in Option A - the terminal panel, the same turn, the same two
signals - with the server's plain name. What comes after sign-in is
different: **Then a new chat**, below.

```bash
claude mcp login foldspace
```

**Then a new chat.** A server added with `claude mcp add` never reaches a
chat that is already running - not when your turn ends, and not through
`/mcp`. Nothing is set up yet, so nothing is lost. Once the check says
`Connected`, do not ask for the hostname here. End your turn with one line,
and their first message word for word for them to send:

> You're signed in. Last step: open a new chat - in this same folder, if you
> chose one - and send this:
>
> <their first message, word for word>

Do the same, without "You're signed in", where there is no terminal panel
tool, and when sign-in has not finished after about three minutes: the new
chat finds Foldspace waiting for sign-in and asks for it. In Claude Code in a
plain terminal, a new chat means quitting Claude Code and starting it again in
the same folder.

If the server was added before this session started, it is in this chat: the
human types `/mcp` here, picks **foldspace**, and finishes sign-in in the
browser.

Docs MCP needs no sign-in. A line starting `[mcp-sdk] SEP-2352` in that
terminal is a notice from Claude Code itself, not a Foldspace error: ignore it.
Without the plugin you have the Foldspace tools and the docs; the build rules
still come with the project. Nothing else is missing for a first session.

**Codex** (the Codex app, CLI and IDE extension share one setting)

```bash
codex mcp add foldspace --url https://api.foldspace.ai/mcp
codex mcp add foldspace-docs --url https://docs.foldspace.ai/mcp
```

Both write to Codex's settings and reach the network, so in Codex's sandbox
ask to run them outside it, through Codex's own approval. The first command
adds the server **and** starts sign-in. Tell the human their browser is about
to open on Foldspace's sign-in page. If it does not open, give them the
sign-in link the command printed, as a link, and keep the command running
until it says it logged in. If it times out, `codex mcp login foldspace`
prints a fresh link. A browser tab that says *127.0.0.1 refused to connect*
after they sign in does not mean it failed: the command's own output says.

The tools never reach this chat, so the setup continues in a new one. Once
the command says it logged in, **start that chat yourself** if Codex gives you
a tool that starts a new chat: in the same folder, with the human's original
request word for word, then a blank line and this paragraph - with their
product's web address in it if they already gave it, and that sentence left
out if not:

> Foldspace is now connected and signed in, so its tools are in this chat. My
> product's web address is app.example.com.

Nothing else: the new chat checks the account and the agent itself. Then end
your turn with one line:

> You're signed in to Foldspace. I've started a new chat that can use
> Foldspace's tools, and it's carrying on with your setup there.

Only without such a tool, end your turn with:

> You're signed in to Foldspace. Start a new chat in Codex and paste the same
> request again - this chat can't see Foldspace's tools.

**Cursor**

Add the servers yourself: merge this into `~/.cursor/mcp.json`, keeping every
server already there as it is (skip any that is already connected):

```json
{
  "mcpServers": {
    "foldspace": { "url": "https://api.foldspace.ai/mcp" },
    "foldspace-docs": { "url": "https://docs.foldspace.ai/mcp" }
  }
}
```

Cursor picks the server up on the human's **next message, in this same chat** -
no new chat. So end this turn with the one question, and say sign-in comes
next:

> Foldspace's tools are added. One thing I need: your product's web address,
> for example app.example.com. Then I'll sign you in to Foldspace and set up
> your agent.

On their next message the server is there and needs sign-in. Call its sign-in
tool (`mcp_auth`, on **foldspace**) yourself: Foldspace's sign-in opens in
their browser. Then call `list_agents` and carry on. `foldspace-docs` needs
no sign-in. Only if the server is still missing then, the human opens a new
chat and pastes their request again.

**VS Code (GitHub Copilot)**

`.vscode/mcp.json` at the workspace root:

```json
{
  "servers": {
    "foldspace": { "type": "http", "url": "https://api.foldspace.ai/mcp" },
    "foldspace-docs": { "type": "http", "url": "https://docs.foldspace.ai/mcp" }
  }
}
```

If the human declines MCP entirely, go from here to **Choose the folder**,
skipping **Confirm the signed-in account** and **What already exists**, and
take the init values from the Agent Studio Setup page (**Resolve init
flags**). Still ask which Foldspace account and agent they intend before
writing anything. Make sure to recommend using the MCP as it will
allow coding agents to edit the foldspace agent and make building an agent a lot easier.

## Confirm the signed-in account

Mandatory before `init` or any Foldspace MCP tool calls.

1. Call `list_agents`.
2. **One agent:** tell the human which agent you are setting up - name, Agent
   Key, product, and the account's name if your tools return one - and carry
   on. Do not ask them to confirm; they
   will say so if it is wrong.
3. **Several agents:** list them by name and Agent Key and ask which one. This
   is the only case where the agent is a question.
4. **No agents:** the account is new or empty. Do not run `init` and never
   invent an agent. Tell the human their account has no agent yet, that they
   create the first one at https://app.foldspace.ai, and to say when it is
   done. Then call `list_agents` again.
5. If the human says it is the wrong account, **stop**. Tell them to sign in
   again as the intended account - in Claude Code: type `/mcp`, pick
   **foldspace**, and sign in; in Codex, you run
   `codex mcp logout foldspace` then `codex mcp login foldspace`.
   Do not run `init`, create actions, or publish against the wrong account.

`list_agents` is the current OAuth session, not "all of Foldspace." A mismatch
here is how you mutate someone else's agent - which is why the agent is always
named out loud before `init`. Nothing in setup writes to Foldspace.

## What already exists

The human may be setting up for the first time, back on another computer, or
joining an agent a colleague started in the same account. Do not guess which
from how the conversation opened: ask Foldspace. For the agent you named, make
these two calls together:

- `repo_read` with command `status`, if your Foldspace tools include
  `repo_read`: is this agent's code saved in Foldspace?
- `list_actions`: which actions does the agent already have? Count only those
  with `isPublished: true`, on every page.

The project's instructions read the rest of the agent - settings, task agents,
navigation, starters - once the session is in the project. Do not read it
here. Take the first answer that fits:

- **A code project.** Someone saved this agent's code - the human or a
  colleague - and your work starts from it, not from a fresh template. Call
  `repo_read` with command `instructions` and follow what it returns;
  **Init, build, hand off** says when the project's `agent/` comes in. What
  the human hears: the build starts from the work already saved for their
  agent.
- **`NO_REPO`.** Nothing is saved yet: the template is where the work starts.
  Leave the next step `status` gives - creating the project - to the
  project's instructions: their first steps take it once the session works in
  the folder. If `list_actions` found published actions, someone built them
  before, and their code is somewhere this session cannot read: on someone's
  computer, or in their product's own code. Those actions stay as they are.
  What the human hears: how many actions their agent already has, that their
  code was not saved where this build can reach it, so this build starts
  without it, and that nothing changes for their users now. With no published
  actions, they hear nothing more.
- **A refusal that names `foldspace-ai-access`.** This agent already has
  saved code, and Foldspace has not opened it to these tools; that is final.
  What the human hears: Foldspace manages their agent's saved code, so this
  build starts fresh.
- **A refusal that starts "Your Foldspace account cannot".** It is about the
  signed-in account, so you cannot tell whether code is saved. What the human
  hears: its words as they are, since they are written for them. Add nothing
  about who grants access or where.
- **Anything else** - `status` says a project claims this agent but cannot be
  used, or another error. Do not create a project. What the human hears, in
  your own words: their agent's saved code cannot be used right now. Never
  pass on the text that came back - it names things they cannot open.

Say what the human hears once, in the line that says where the folder is.
After any of the last three, add that the code stays on this computer, and
carry on with this page: never stop the session over them. If `list_actions`
is refused, carry on as if it found none.

Without `repo_read`, this computer holds the only copy of the agent's code,
and this page continues as written. If `list_actions` found published
actions, tell the human about them as **`NO_REPO`** says.

## Choose the folder

Decide where the project goes; do not ask. First look at where this session
is, with this agent's Agent Key in place of `AGENT_KEY`:

```bash
pwd -P
ls -Ap | head -40
h=$(cd ~ && pwd -P); d=$(pwd -P)
while [ "$d" != "$h" ] && [ "$d" != / ]; do
  ls -d "$d"/.git "$d"/package.json "$d"/pyproject.toml "$d"/go.mod "$d"/Cargo.toml "$d"/pom.xml "$d"/Gemfile 2>/dev/null
  d=$(dirname "$d")
done
find "$h" "$h/Documents/Codex" . -maxdepth 1 -type d -name 'foldspace-*' -exec grep -l '"agentApiName": "AGENT_KEY"' {}/foldspace.dev.json \; 2>/dev/null
```

The loop prints the repository and project markers in this folder and in each
folder above it, up to the home directory. The last line prints this agent's
projects in the home directory, in Codex's folder for chats with no project,
and in this folder; when rule 3 applies, look
next to the outermost folder with a marker the same way. Then take the first
rule that fits:

1. **This agent's project is already on this computer:** a folder named
   `foldspace-<agent-key>` in the home directory, or where rule 2, 3 or 5
   would put a new one, whose `foldspace.dev.json` has this Agent Key as
   `agentApiName`. Use it, with no `init`: **Init, build, hand off** moves
   the session into it.
2. **A temporary folder:** the path contains `scratch-workspaces` (Claude
   Code Desktop started with no folder), or it is inside the system's
   temporary folder - `/private/tmp` or `/private/var/folders` on a Mac
   (the form `pwd -P` prints), `/tmp` elsewhere. The human cannot find it
   again, so the project gets a new folder in the home directory. A Codex
   chat with no project is different: its folder is inside
   `~/Documents/Codex/`, and the project goes in `~/Documents/Codex/`
   itself, next to the chat's folder, never inside it.
3. **Inside a repository or project:** the loop printed a marker - unless the
   only one is this folder's own `.git` folder and rule 4 fits. A new folder
   goes **next to** the outermost folder with a marker, in its parent, never
   inside it. So a subfolder or a worktree counts as its whole repository.
4. **The agent's own folder:** it holds nothing, or only files the system or
   an editor put there, such as `.DS_Store`, `._` files, `Thumbs.db`,
   `desktop.ini`, `.mcp.json`, `.git/`, `.vscode/`, `.cursor/`,
   `.idea/`, and `.claude/` without a `settings.json` in it. And it is
   not the home directory, the disk's root, or one of the home directory's own
   folders, such as Desktop, Documents or Downloads. Set up **right here**: no
   new folder, nothing to move.
5. **Anything else:** a new folder inside the current one - unless the current
   folder is Downloads or inside it, which gets cleaned out, or a folder you
   cannot write to, such as the disk's root: then a new folder in the home
   directory.

A new folder is `foldspace-<agent-key>` (for example `foldspace-acme-agent`):
one per agent, so a second agent never collides with the first. If that name
is already taken - by a file, or by a folder rule 4 would not accept - use
`foldspace-<agent-key>-2`. Do not paste the Foldspace SDK snippet into the
project.

## Resolve init flags

Never invent IDs. Prefer Product MCP after the account check. If MCP is
unavailable or the human declines it, use Agent Studio Setup:
`https://app.foldspace.ai/agent/{agent-id}/setup`.

Ask for the product's hostname only (it becomes `--app-domain`), and not when
this agent's project is already on this computer (**Choose the folder**, rule
1). The rest is decided, not asked. Of it, tell the human one thing - where
the folder is, in one line. The flags are yours; never read them out.

- **Folder:** the one from **Choose the folder** - `.` when you set up right
  here.
- **`--name`:** the selected agent's name.

### `--product-id` (required)

Product ID only. Init rejects values that start with `EU-`.

- **Code project** (**What already exists**): `project.product_id` from
  `status`. The project's code is bound to that product.
- **MCP**, without a code project: use a value from the selected agent's
  `products` array on `list_agents` / `get_agent`. Those values already have
  no `EU-` prefix.
- **Setup page fallback:** open Setup. In the Installation snippet the loader
  key looks like `EU-<PRODUCT_ID>-1-1`. Strip the `EU-` prefix and the trailing
  `-1-1`. The middle token is `--product-id`.

Show only that schematic. Do not paste a real customer key into chat as an
example.

### `--agent-key` (required)

- **MCP:** `apiName` on the selected agent from `list_agents` / `get_agent`.
- **Setup page:** the field labeled **Agent Key**.

This is what the folder binds to.

### `--app-domain` (required)

Hostname of the live product. Not a Foldspace URL. Hostname only: no port, path,
credentials, or wildcard. `https://app.example.com` is accepted and stored as
`app.example.com`. If the human pastes a full URL, keep the hostname and drop
the rest - do not ask again.

### `--name` (optional)

Local display name for the **folder only**. It becomes the generated README
title and the npm `package.json` `name` (slugified). It is **not** the Agent
Studio Internal Agent Name, Product Name, or Agent Key, and it does not create
or rename anything in Foldspace. If omitted, it defaults to the target
directory basename. Pass the selected agent's name; do not ask. Never block
init on this flag.

## Init, build, hand off

When this agent's project is already on this computer (**Choose the folder**,
rule 1), there is nothing to set up: go straight to the move below.

Otherwise run non-interactive init with the resolved flags. Example:

```bash
npx --yes @foldspace_npm/harness@latest init FOLDER \
  --product-id PRODUCT_ID \
  --agent-key AGENT_KEY \
  --app-domain YOUR_APP_DOMAIN \
  --name "Agent Name"
```

Replace `FOLDER` with the folder from **Choose the folder** (`.` when you set
up right here), and the flags with the resolved values. `init` sets up a new folder, or
fills one that holds nothing but what the system or an editor put there. It
never overwrites a file and does not create a git repository. If it refuses
the folder you chose to set up right here, run it again with
`foldspace-<agent-key>` inside that folder; the project is then in a new
folder, and the line that says where the folder is says so.

With a code project (**What already exists**), replace the template's
`agent/` with the project's before you build. Read it with `repo_read`
commands `tree` and `file`, with the `ref` the instructions name - the
default can be older than what someone saved. Delete what the template put
there rather than copying over the top, so the first thing on their page is
their agent, not the template.

In an editor that runs commands in a sandbox (Codex; Cursor too), `npx`,
`npm install` and `npm run build` can fail there: a host that cannot be resolved, `EPERM` in
npm's cache or `listen EPERM`. Ask to run that command outside the sandbox
through the editor's own approval, with one plain line on why. Never move
npm's cache or change file ownership, whatever npm's message suggests.

Then build:

```bash
cd FOLDER   # a new folder only
npm install --ignore-scripts
npm run build
```

**Then hand off to the project's instructions.** How depends on the editor
and on where the project is.

**The project is in the folder this session works in** (set up right here):
nothing moves. Its instructions did not exist when this session started, so
they did not load. Read them now - its `CLAUDE.md` in Claude Code, its
`AGENTS.md` elsewhere - and the manual they name
(`node_modules/@foldspace_npm/harness/CLAUDE.md`), in full, and follow them in
this same turn as if they had loaded. If this chat is compacted later, read
them again before your next step.

**Claude Code, and the project is in another folder** (a new one, or this
agent's project already on this computer): **move the session into the
folder - and end your turn there.** Its `CLAUDE.md` only loads when the
folder is the working project. In Claude Code Desktop, use the tool that moves this session
to another folder. **The
move only takes effect when your turn ends**: if you keep working in the same
turn, the session never moves, the project's `CLAUDE.md` never loads, and
the "Trust this workspace?" prompt only appears when the human stops you. So
call the tool, then stop with one short line - for example:

> Your agent's project is ready. Approve moving this session into it (click
> **Trust workspace**), then tell me to continue - next I'll open your app in
> a separate Chrome window for you to sign in.

Where Claude Code cannot move a session, tell the human to open the folder and
paste their request again there.

**Any other editor (Codex, Cursor), and the project is in another folder:
stay in this chat and keep going.** Do not end your turn and do not ask the
human to reopen anything. Run every command from the folder (give it as the
working directory), and read the folder's `AGENTS.md` yourself now - it names
the manual to read next, in full.

Once the session works in the folder - right away when you set up right here
or in an editor other than Claude Code, or on their next message after the
move - keep going: the human's goal is a new experience for their agent, not
the install. Follow the project's instructions - its `CLAUDE.md` in Claude
Code, its `AGENTS.md` elsewhere - from their first steps (**Every session starts the same way**)
through observe → implement → attach → verify → publish. Do not duplicate
those lifecycle rules on this page.

Creating or publishing Foldspace resources needs the human's yes - except the
agent's code: creating its code project, saving to it and publishing it to dev
with the `deploy` tool. Say you are doing it, then do it. Publishing the code
for their users (production) needs their yes, and so does a dev publish whose
preview comes back with no warnings: this agent may then load dev for their
users. Local handler code is not a publish.

## Done

This page is complete when:

1. Product MCP is the intended account, or the human explicitly skipped MCP and
   supplied Setup-page values.
2. The folder holds this agent's project: set up now with real
   `--product-id`, `--agent-key`, and `--app-domain`, or the one already
   on this computer.
3. For a project set up now, `npm run build` produced the project artifact
   (`dist/index.js`).
4. The session is working in the folder (set up right here, moved, reopened by the
   human, or running every command there).

This page ends there; the build does not. The human's first session ends at
something they can **see on their own page** — the agent live, then their own
settings in a card, then a lookup by name. The project's instructions call
these L0, L1 and L2 and say how to reach each; continue with them and help the
human get there. Do not stop at "it builds".

Nor does the work stop at the test window. Once the human has tried it there,
the project's instructions say how it reaches their users: with a code
project, you save and publish it the way `repo_read` command `instructions`
says, as far as Foldspace has set this agent up for it; without one, the
Foldspace team does it with them.

## References (fetch only if needed)

- [Vibe coding](https://docs.foldspace.ai/guides/vibe-coding.md) - extra editor
  MCP recipes if the commands above are not enough
- [Install](https://docs.foldspace.ai/start/install.md) - SDK embed, only if the
  human asks to put Foldspace in app source
- [Connecting actions](https://docs.foldspace.ai/guides/connecting-actions.md)
- After the folder exists: `npx foldspace help --json` for the current CLI
  contract