08Working with artefacts

Projects: how agents file their work

A project is a shelf in your library. Agents name one by its path, such as RentOS/Backlinks, and read each project’s one-line description to decide where new work belongs. Write the description once and every agent you connect files in the right place without being told.

A path, up to three deep

Projects are named the way folders are: by a path, with a slash between levels. Clients is a project, Clients/Acme is a project inside it, and Clients/Acme/Website goes one level further. Three levels is the limit. Ask for a fourth and the publish is refused with a message saying so, which is enough for an agent to pick a shallower path and try again. Each name can be up to 100 characters.

Three levels, each inside the last. The artefact is filed in the most specific project that fits.

Two things make paths forgiving. Any part that does not exist yet is created as the artefact arrives, so publishing into RentOS/Backlinks makes both projects if you have neither. And names match ignoring case, spaces and punctuation: rentos/back-links lands in RentOS/Backlinks, so two agents with different habits never split one project into two.

How an agent picks a project

It calls list_projects. The answer lists every project, nested ones included, with its path, its description, how many artefacts it holds itself (archived ones and subprojects aside) and when something was last published there.
It chooses the most specific project that fits. The tool tells agents to prefer an existing project, and to start a subproject of an existing one before a new top-level project.
It publishes with project. When the path is new, it adds project_description: one sentence on what belongs there, for the agents that come after it.
It reads the reply. If the publish started a new project, a project_note says so and names similar projects that already exist.

A call looks like this. The same project and project_description fields work on publish_artifact, update_artifact and create_upload_url.

{
  "title": "Backlink audit, October",
  "project": "RentOS/Backlinks",
  "project_description": "Link-building research and outreach lists for the RentOS site."
}

The note is the safety net. Suppose an agent files into a new top-level Backlinks while RentOS/Backlinks exists. The reply says:

Started a new project "Backlinks". Similar projects already exist: "RentOS/Backlinks". If it belongs in one of them, move it there with update_artifact (slug and project only, no content needed).

The agent moves it with one more call, nothing is uploaded twice, and the stray project tidies itself away (more on that below). An agent that is still waiting for your approval sees no projects at all, since it may not read your library yet. It names the project it thinks fits, and the forgiving match does the rest.

The description is the instruction

Every project can carry a description of up to 500 characters. Agents read it in list_projects before they file, so it is the one place where a sentence from you steers every agent at once. Write it the way you would brief a new colleague:

Clients/AcmeEverything for Acme: proposals, reports and the drafts we send them.
RentOS/BacklinksLink-building research and outreach lists for the RentOS site. Not general SEO.
Home/TravelItineraries, booking comparisons and packing lists. One artefact per trip.

An agent’s project_description only fills a project that has none. Once you have written your own, no agent can overwrite it.

Organise projects in the library

Projects sit in the rail, under Projects. Parents fold open to show their subprojects, each count includes everything nested inside it, and hovering a project shows its description. Pick one and the sheet shows its artefacts and those of its subprojects. Search finds artefacts by project name too.

The pencil beside a project opens Edit project, with three fields:

Field	What it does
Name	Renames the project. A slash is not allowed here: nest with Inside instead.
Inside	Moves the project to Top level or into another project, as long as the result stays within three levels.
What goes here	The description agents read. The dialog puts it plainly: agents read the description to decide what to file here.

Rename or move a project onto a sibling of the same name and the button changes from Save to Merge: its artefacts and subprojects move into the one already there, which keeps its own description unless it had none.

To move a single artefact, open it in the loupe and use the Project menu. Choose None, any existing project, or New project… to type a path such as Parent/New project and press Enter. An agent can do the same with update_artifact, passing only the slug and the new project.

Empty projects tidy themselves

When the last artefact leaves a project, because it was moved or deleted, the project is removed, as long as it has no subprojects and no description. Its parent gets the same check, so emptying Hotels/Watch can clear an empty Hotels as well. The stray projects agents start by mistake disappear the moment their one artefact is moved to where it belongs.

A description is what keeps a shelf in place. If you want a project ready for work that has not arrived yet, describe it, and it stays. Archived artefacts still count as filed, so archiving does not remove a project, although the rail only shows projects with something live in them.