<!-- source: https://docs.dreamlake.ai/workspaces/project-addresses @ 0.1.192 b2f973b1 -->
# Project names and addresses

A project's name is its display label. Its slug is the URL segment at
`/<namespace>/projects/<slug>`. Its stable ID identifies the same project across
name, slug, and ownership changes.

Open **Edit Project** to change its name. Under **Project address**, choose
**Follow project name** or **Custom slug**. The dialog shows the current and
proposed addresses before saving. Custom slugs persist when the name changes;
selecting Follow project name immediately derives the address from the current
name and enables future automatic changes.

New projects created without an explicit slug follow the name. Existing projects
without recorded slug preferences retain their address. A historical name/slug
mismatch cannot distinguish a stale address from an intentional custom URL;
there is no automatic migration of those projects.

Name, slug, mode, and descendant paths change in one transaction. Editing
requires Project ADMIN. A collision or stale revision refuses the whole edit;
no numbered fallback is selected. ASCII and Unicode names use the same
established slug derivation as project creation. Names containing non-ASCII
characters receive a deterministic short hash so distinct names remain
addressable. Custom slugs use the project's existing single-segment rules and
100-code-point limit. New custom slugs cannot be 24 hexadecimal characters,
which the API reserves for project IDs; automatic slugs prefix such names with
`project-`.

## Existing links

Previous browser addresses resolve to the current project, including their
nested path, query, and fragment. The browser replaces the old history entry;
Back does not loop through the old address. Unsaved editors remain protected by
the existing navigation guard. Historical slugs remain reserved for the stable
project identity and cannot be reused by another project.

An old address never grants access: location lookup checks current permissions.
Deleting the project makes its historical links unavailable. Integrations should
store the stable ID; an old slug is not an instruction to replay a write.

## REST and clients

Read the project to obtain `id`, `slugMode`, and `slugRevision`. Address the
mutation by explicit namespace and project ID:

```http
PATCH /namespaces/my-team/projects/507f1f77bcf86cd799439011
Content-Type: application/json

{"name":"Research Results","expectedProjectId":"507f1f77bcf86cd799439011","expectedSlugRevision":3}
```

| Input | Result |
| --- | --- |
| `name` alone | Changes the display name; auto mode derives its slug, custom mode preserves it |
| `slug` | Sets that exact slug and custom mode |
| `slugMode: "auto"` | Derives the slug now and on future renames |
| `slugMode: "custom"` | Keeps the current slug on future renames |
| `slug` with `slugMode: "auto"` | Invalid; choose one |

`expectedProjectId` binds the edit to the loaded project.
`expectedSlugRevision` rejects stale name/address edits with HTTP 409. A
successful response includes the canonical slug and new revision. Metadata
`displayName` edits follow the same policy; the generic Node API retains its
existing `name`-means-slug contract and treats it as an explicit custom slug.
Slug preferences use dedicated server fields; a metadata patch cannot override them.

`GET /namespaces/:namespace/projects/:oldSlug/canonical-location` returns the
current readable namespace, project ID and slug. Use it for link resolution;
mutations must use the verified current identity. CLI `dl project rename`,
TypeScript `client.projects(namespace).update`, Python `client.projects.update`,
and MCP `project_get` / `project_update` expose the same settings and guards.
After an uncertain write, inspect by ID before retrying.
