> ## Documentation Index
> Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Set up a Project
> Give a project a goal, the repositories it is about, and the places it may take events from.
A **Project** is a scope: a goal, the repositories that goal is about, and the
places Cogno may take events from on its behalf. Its tasks gather on its own
page, and the work Cogno runs for it runs in a checkout you nominate.
Open **Projects** from the sidebar. The page is a ledger of that configuration —
one card per project showing its name and its goal. It carries no progress bars,
percentages, or date chips; progress lives in [Tasks](/docs/tasks) and on the
project's own page.
## Prerequisites
* A workspace you can write content in.
* **GitHub** connected, if you want to name the repositories a project is about
— see [GitHub](/docs/github-integration). Without it the repository picker reads
**Connect GitHub to choose repositories.**
* A connected integration, if you want the project to reach one — see
[Integrations](/docs/integrations).
## Create a project
On an empty workspace the same button sits under **No projects yet**.
Fill in **Project name**. **Goal** is the sentence the project is judged by
— *What does finishing this project look like?* — and is capped at 200
characters, because it is a goal rather than a plan.
Under **Repositories**, select **Choose repositories** and pick from what
Cogno has read from GitHub. **Add another** adds more.
Both this and the goal are optional at creation and editable afterwards, as
the dialog says: *A project is a goal and the repositories it is about. Both
can be changed later.*
The **+** may open a menu instead of the dialog — **Open project** picks a
folder on this machine, **Open GitHub project** opens the dialog above, and
**Recents** lists checkouts the machine has seen.
## Write the project's goal
The project's page has a **Configuration** card on the right. Its
**Instruction** section holds the same sentence the create dialog called the
goal — what this project is *and* how Cogno should act in it, written once. An
unwritten one reads **Say what this project is and how Cogno should act in it**.
Select the text to edit it. It saves when you click away; **Escape** reverts.
This is the text the **Projects** cards show, so a project you describe well is
a project you can recognize from the ledger. A card with nothing written reads
**No description yet**.
Above it, **Owner** names the member who owns the project; unset, it reads **No
owner**.
## Choose what the project may reach
**Filter** in the **Configuration** card is the project's boundary on your
workspace's integrations: *Cogno only takes events from what is listed here.*
Nothing listed means nothing reached — the default is closed, and an unfiltered
project reads **Nothing yet**.
One row per connected tool, each with its own **+**.
Search with **Search \**. When a tool has nothing left to offer,
the picker reads **Nothing left to add.**
Remove a place with the **✕** on its chip (**Remove \**). A project
may list up to 500 places per tool.
| Tool | What a place is |
| ------------ | ---------------------------- |
| **Slack** | A channel. |
| **GitHub** | A repository, as `org/repo`. |
| **Discord** | A channel. |
| **ChatWork** | A room. |
| **Sentry** | A project, by its slug. |
| **Notion** | A page. |
A tool your workspace has not connected draws no row. Connect it from
[Integrations](/docs/integrations) and reopen the project.
## Name the repositories the project is about
**⋯ → Edit repositories…** in the **Configuration** card's header opens
**Repositories**: *Which repositories this project is about. A worker
environment must hold every required one to run its work.* A project may name up
to 20.
This is what makes a worker environment usable for the project, so narrowing it
can strand a checkout somebody is already working in. Cogno refuses that edit
and says what it would break — **This change strands environments already
serving this project**, naming what each is missing and who it affects. Select
**Change anyway** to proceed regardless.
## Choose where the project's work runs
Which control you see depends on your workspace.
The project's own checkout. Cogno looks for a folder on this machine holding
every repository the project requires — **Looking for a matching folder…** —
and then offers what it found:
| The control reads | What it means |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use \** | A registered environment already holds every required repository. Hover for *\ already has every repository this project requires*. |
| **Set up in \** | A folder qualifies but has no worker yet; accepting starts one there. |
| **Set up a worker…** | Nothing qualifies. **Clone this project onto a worker…** clones fresh; **Use a local folder that has the repositories…** points Cogno at a folder you already have. |
**Teammates' environments** lists what everyone else nominated, read-only —
each machine is its owner's answer.
The per-person binding: your machine and checkout for this project's work.
A project is shared, a checkout is not, so your choice never writes anyone
else's. Unset it reads **Not set**; **Clear** unbinds it. **Teammates'
repositories** shows everyone else's, read-only.
See [Getting started](/docs/getting-started) for connecting a machine in the first
place.
## Set the dates
**Dates** carries **Start** and **Target**. An unset one reads **Set date** to
whoever may set it, and is simply absent for a reader who may not — an empty
pill that opens nothing is an invitation you cannot take.
## Narrow the project's task list
Under the project's name is the same search box and **Filter** the
[Tasks](/docs/tasks) page carries, scoped to this project. Type into **Search title
or #123...** to search by name, or open **Filter** for the criteria:
| Criteria | What it narrows to |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| **Status** | Which lanes are listed. **Open** selects the four unfinished ones; **All** clears the criteria. |
| **Tag** | Tasks carrying a tag, or **No tag**. |
| **Assignee** | A person, or **Unassigned**. |
| **Start** / **Due** | Started, today, this week, or no date. |
There is no **Project** criteria here — the page is already one project, and the
filter cannot take the list outside it.
The list opens on Backlog, Ready, In Progress, In Review and Done; Archived and
Rejected are left out until you ask for them. **Reset** in the panel's header
returns to exactly that, and **Clear filters** at its foot drops every criteria
while keeping what you typed in the search box. A filter that matches nothing
reads **No tasks match this filter** — the project still has its tasks.
The filter is not remembered: leaving the project and coming back opens the
full list again. Saved views live on [Tasks](/docs/tasks), not here.
### A list too long for one page
A project with hundreds of tasks does not send them all at once. The page opens
on the first stretch of the list and fetches the rest as you scroll; the foot of
the list says **Load more — showing 50 of 240** and loads it on its own as you
reach it, or on a click.
While a group is still filling, its count reads `12+` rather than a number. Only
the last group on the page can be in that state — the ones above it are complete
and count exactly. The **From Cogno** lane is never partial: it is fetched
whole, separately, so a proposal is never hiding further down the list.
## Answer what Cogno proposes
A project's still-unaccepted tasks gather in a **From Cogno** lane above the
status groups on the project's page — the same lane [Tasks](/docs/tasks) carries for
the whole workspace. A task stays there until a person answers it; accepting
drops it into its status section below.
Two ways to answer:
* **From the lane** — hover a row for **✓** (**Accept suggestion**) and **✕**
(**Dismiss suggestion**).
* **From the task** — open it, and the right rail carries Cogno's own card.
There is no approve button: **Pick a status to accept it** — choosing a status
from the card's status chip *is* the acceptance. **✕** dismisses.
Where each proposal came from, and everything else about accepting them, is in
[Work with Tasks](/docs/tasks#the-suggested-lane).
## Delete a project
**⋯ → Delete project** in the **Configuration** card's header. Cogno names what
it holds first — *This project has N tasks. Deleting it cannot be undone.*
Deleting a project cannot be undone.
## Reference
### The Configuration card
| Section | What it holds |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | The member who owns the project. **No owner** when unset. |
| **Instruction** | The project's one free text — what it is and how Cogno should act in it. Shown on the **Projects** cards, where it is cut to 240 characters. |
| **Dates** | **Start** and **Target**. |
| **Runs in** / **Worker Environments** | Where this project's work runs — the project's own checkout, or your personal binding. |
| **Filter** | The places this project may take events from. |
The header's **⋯** menu carries **Edit repositories…** and **Delete project**.
Any workspace member with content-write permission can edit the card; a reader
sees values instead of controls.
### The Projects card
| Part | Meaning |
| ---- | ----------------------------------------------------- |
| Name | The project's name. Select the card to open it. |
| Body | The project's instruction, or **No description yet**. |
### Limits
| Thing | Limit |
| -------------------------------------------- | --------------------- |
| Goal, at creation | 200 characters |
| Instruction, as shown on a **Projects** card | Cut to 240 characters |
| Repositories per project | 20 |
| Places per tool in **Filter** | 500 |
## Troubleshooting
| Symptom | Likely cause | Fix |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| The repository picker reads **Connect GitHub to choose repositories.** | GitHub is not connected. | Connect it from [Integrations](/docs/integrations). |
| The picker reads **Cogno has not read your GitHub yet. Check back shortly.** | Connected, but the first sync hasn't finished. | Wait and reopen it — connecting a tool doesn't read what's inside it. |
| The picker reads **No repositories yet. Check what Cogno can see in GitHub.** | The sync ran and found nothing. | Check the App's repository access on GitHub's side. |
| A tool has no row under **Filter** | The workspace has no active connection for it. | Connect it from [Integrations](/docs/integrations), then reopen the project. |
| **Runs in** offers **Set up a worker…** and nothing else | No registered environment holds every required repository. | Use **Clone this project onto a worker…**, or narrow the repository list under **⋯ → Edit repositories…**. |
| **That folder doesn't have \** | The folder you pointed at is missing a required repository. | Pick a folder holding all of them, or drop the requirement. |
| Saving the card says **You don't have permission to change this project's configuration.** | You have read access, not write. | Ask a workspace **Owner** or **Admin**. |
| A repository edit is refused with **This change strands environments already serving this project** | The new scope would leave a teammate's checkout unable to run the project's work. | Restore the repository, or select **Change anyway**. |
For anything not listed here, see [Troubleshooting](/docs/troubleshooting).
## Related docs
* [Work with Tasks](/docs/tasks) — the statuses, the **From Cogno** lane, and accepting suggestions.
* [Concepts](/docs/concepts) — how events, the agent, and workers fit into one loop.
* [Integrations](/docs/integrations) — connect the tools a project can reach.
* [GitHub](/docs/github-integration) — connect the repositories a project is about.
* [Instructions](/docs/instructions) — the standing workspace rules Cogno follows everywhere.
* [Getting started with Cogno](/docs/getting-started) — set up the loop end to end.