# Projects and folders > How projects group documents, how linking a repository lets agents find the right project, and what happens the first time an agent works in a new folder. ## Projects A project collects the documents for one piece of work, usually one repository. Every document belongs to a project, and every project belongs to a workspace. Documents are numbered within their project, as in "#12". Your projects are listed in the sidebar and on the **Projects** page. To create one, click **New project**, give it a name, and optionally a repository URL. Owners, admins, reviewers and members can create projects; viewers can't. ### Pick a repository from GitHub If the workspace has the [GitHub app](https://planpage.dev/docs/github.md) installed, **New project** lists the repositories it's installed on. Type to filter the list, then click a repository or move to it with the arrow keys and press Enter. planpage fills in **Repository URL**, and fills in **Name** with the repository's name unless you've already typed one. If GitHub isn't connected yet, **New project** shows a **Connect GitHub** box in place of the repository field instead. Owners and admins can click **Install on GitHub** right there; everyone else is told who can. Click **Enter a repository URL instead** to type a URL without installing the app. The list is ordered so the likely choice comes first: 1. repositories no project in the workspace uses yet, most recently pushed first, 2. archived repositories, 3. repositories already linked to a project, tagged "Linked to" and the project's name. You can still pick one; two projects can share a repository. For a GitLab or Bitbucket repository, or a GitHub repository the app isn't installed on, click **Enter a URL instead** and type the URL. Editing the URL by hand also clears the picked repository. Everyone who can create projects in the workspace sees every repository the app is installed on, including private ones. If the workspace hasn't installed the app, owners and admins see an **Install on GitHub** link. After installing, GitHub sends them back to the form with the list filled in. Other members see a note that an owner or admin can install the app in **Workspace settings → Integrations**. Either way, you can type a URL as before. Each project has its own page with **Documents**, **Activity** and **Project settings** tabs. Under **Project settings** you can rename the project and change its repository URL. Right-click a project in the sidebar, on the **Projects** page or in **Workspace settings → Projects**, or use the **⋯** beside it, for its menu: **Open**, **Copy link**, **New document here**, **Write a brief**, **Rename**, **Link repository** (or **Change repository**) and **Archive**. You see the items your role allows. ## Link a repository A project's **Repository URL** is how agents find it. When an agent starts work in a folder, it reads the folder's git remote and calls `resolve_project`. planpage compares the remote with each project's repository URL and returns the match. The comparison ignores the differences between remote formats, so these all match the same project: - `https://github.com/acme/api` - `https://github.com/acme/api.git` - `git@github.com:acme/api.git` Use an https or git@ URL. One project links to one repository. The GitHub integration uses the same URL to decide which pull requests can link to the project's plans; see [GitHub](https://planpage.dev/docs/github.md). ## The first time in a folder If no project matches the folder's remote, the agent doesn't guess. It tells you planpage doesn't know where this folder's plans go yet and asks you to choose: - one of your existing projects, listed with their workspaces, or - a new project, with a name suggested from the repository or folder. When the remote is a GitHub repository the workspace's app is installed on, `resolve_project` returns its name as `suggested_name` and the agent uses that. Then it remembers your answer: - For a new project, it calls `create_project` with the repository URL set. You can choose which workspace it goes in; `whoami` lists every workspace the connection can reach, including empty ones. - For an existing project, it calls `link_repository`, which saves the remote on the project. From then on `resolve_project` finds the project and the agent doesn't ask again. If the project is already linked to a different repository, the agent asks you before replacing the link, or suggests a separate project for this repository. A folder with no git remote can't be remembered. The agent asks once per session. It can call `list_repositories` to offer the repositories the workspace's GitHub app is installed on, most recently pushed first, each marked with the project already linked to it. `whoami` shows, for each workspace, whether the app is installed and how many repositories it covers. ## Archive a project Owners and admins can archive a project from **Project settings**, with the **Archived** checkbox in **Workspace settings → Projects**, or with **Archive** in the project's menu, which asks first. Archiving hides the project from the sidebar and from agents' project lists. Its documents stay readable, nothing is deleted, and you can restore it in the same places. ## Delete a project Owners and admins delete a project from **Workspace settings → Projects**: click **Delete…** on its row, then **Move to Trash**. In your personal workspace you can delete your own projects. The project and every document in it disappear for everyone straight away: from lists, search, the Inbox, share links, guests and agents. Anyone with the document open is disconnected. Deleted projects wait in **Trash**, at the bottom of the same page, for 30 days. **Restore** brings the project back as it was, share links included. **Delete now** deletes it for good at once. After 30 days planpage deletes it for good automatically, with every version, comment, review and activity entry. Agents can archive projects but can't delete them.