Creating a Project

There is no New Project button, and none is missing: a project record comes into existence the first time NEXUS needs one — the first time a session's working directory resolves to a folder no project record covers yet. Running a session in a folder, pinning a rule from it, or any other action that asks "which project is this?" creates the record as a side effect.

What gets recorded

• Identity: the folder's canonical path.
• Display name: the folder's name by default — a session in ~/code/acme produces a project named acme.
• Linked workspaces: the workspace the resolving session belonged to. The set grows as sessions from other workspaces work in the same folder — see Scope & Membership.

The identity rule: one folder, one project

Project identity is the folder's real path: before matching, the path is expanded (~), resolved through symlinks, and normalized (.., trailing slashes). Every spelling of the same folder — a symlink to it, a ../-relative route into it — lands on the same project record, never a duplicate.

The rule cuts the other way too: two directories that hold the same content are two projects. A repository checked out twice — including two git worktrees of one repo — is two folders, and therefore two project identities. See Project Model.

Nothing is written into your folder by creation

Creating a project record touches only NEXUS's own storage. Files appear inside the project folder only when something puts them there — pinning a rule or data mapping exports .chainabit/memory/rules.md / data-map.md, and linking an agent has its own previewed, consent-gated writes (see Paths & Credentials).

Where to go next

• Scope & Membership — what being "in" a project means for workspaces and agents.
• Pinning & Promotion — the first thing most projects are created for.