Project Model

Four nouns in NEXUS describe things that often — but not always — coincide: the workspace, the project, the repository, and the chainy. Each answers a different question, and conflating them produces wrong expectations about where memory and configuration travel, and about what a piece of work belongs to.

The four nouns

Noun	Identifies	Owned by
Workspace	A container inside NEXUS: sessions, agents, files, and a layout, switched as a unit.	NEXUS — created and deleted in the app.
Project	A working folder on disk, by its real path — and, separately, a container in work management that boards belong to. Two records, one word; see below.	NEXUS. The folder is yours.
Repository	A git repository — branches, worktrees, history.	git. NEXUS only reads its layout, through the read-only repo_* and worktree_* tools.
Chainy	A grouping in your Chainabit account, in the cloud. A work item can carry a link to one.	Chainabit — it exists on the account, never on your machine.

Why workspace ≠ project

A workspace is an arrangement of work; a project is a place on disk. The two cross:

• Several workspaces, one project. Two workspaces whose sessions both run in ~/code/acme share one project — and therefore share its pinned rules and project-scoped memory. The project follows the folder, not the workspace.
• One workspace, several projects. A single workspace can host sessions working in different folders; each session resolves to its own project.

Deleting a workspace destroys workspace-scoped things — its sessions, layout, canvases, and workspace-scoped memory. It does not delete a project: the folder, its committed .chainabit/ files, and its project-scoped memory remain, still shared with every other linked workspace.

Why project ≠ repository

A project is any folder a session works in — it does not have to be a git repository. And a repository does not define project boundaries either: a repo checked out into two directories (say, two worktrees) is two distinct folders and therefore two distinct project identities, while git regards them as one repository.

What makes a folder a project is use: the first time a session's working directory resolves there, NEXUS records the project. The identity rule is realpath normalization — spelling the same folder through a symlink, ~, or .. resolves to the same project, never a duplicate.

One word, two project records

"Project" covers two records that are stored separately and do not automatically see each other. Which one you are looking at depends on the surface that asked.

	The folder identity	The work-management project
What it is	A working folder, by its real path	A container that boards, stages, and cards belong to
How it comes to exist	Derived: the first time a session's working directory resolves there	Created deliberately, with a title and a status
Carries	Canonical path, linked workspaces, pinned rules, project-scoped memory	Title, status, and its boards
Where you see it	The Pinned Memory panel, an agent's Memory card, .chainabit/memory/ exports	The Work destination's Projects surface

The two overlap in practice — the folder you work in is usually the project you are planning — but a work-management project created in the Work destination has no folder attached to it, and a folder identity derived from a session does not appear on the Projects surface. Neither is a bug to route around; they answer different questions, and a surface knows which one it is asking.

Why a project is not a chainy

A chainy is a cloud grouping. A project is local. A project may link to a chainy; it is never identified with one.

• Membership is computed locally, and never through the link. A work item belongs to a project because its card sits on a stage of a board of that project. It references a chainy through a separate, optional link. Nothing derives project membership from that link.
• A project created offline is a complete project. It has a locally minted id, a status, and boards, and it has no chainy at all. Nothing about it is pending.
• What the two genuinely share is the status vocabulary, not identity. A project's status — active, paused, completed, abandoned, archived — is the same set a chainy uses. That overlap is what makes them look interchangeable. It is a shared vocabulary, not a shared record.

The product's own wording is inconsistent here, and deliberately so: the interface says Project, the web route is /projects, and the API type is called a chainy. All four spellings are load-bearing contracts, so none of them is being changed to match the others. When you read "chainy" in an API context and "project" in the app, expect a link between two things — not one thing under two names.

Because a chainy lives on the account and nothing replicates between the account and this machine today, a link to one is an opaque reference: NEXUS counts it and shows it, and does not resolve it. See Local-first.

What each noun scopes

Concern	Scoped by
Sessions, panes, layout, canvases	Workspace
Workspace-scoped memory	Workspace
Pinned rules & data mappings, project-scoped memory, .chainabit/memory/ exports	Project (folder identity)
Boards, stages, cards, and the planning surfaces they feed	Project (work-management record)
Branch and worktree layout shown to agents	Repository (read-only)
Nothing on this machine	Chainy — it is a link, not a scope

Where to go next

• Projects — the guide to how the folder-identity project record comes to exist and what membership means.
• Work § Projects — the work-management project: its status, the read-only rule, and what scoping the planning surfaces to one does.
• Workspaces — the workspace as a container.
• Memory scopes — the visibility rules the project scope participates in.