# Project notes

A project's notes are Markdown documents next to its parts: what the product is for, what was decided and why, what was checked and what is still open. The user and every agent after you read them, so a note is where a session's understanding outlives its chat. Notes change only through plans, like any document.

Read [Working with plans](working.md) first.

## Read them first

Before you work on a project, read its notes: `list_projects` lists each project's notes (`noteId`), and `inspect_document` on a note returns its `text`, its `outline` (the headings) and the documents it `links` to. Follow what they say was decided unless the user asks otherwise, and do not redo checks they list for the revision that is still current.

## Keep them at the end

At the end of a session that decided, built or checked something, propose an update to the project's notes. Make a note with `create_note` when the project has none: it starts with these headings, or only the ones you pass in `sections` (for example `["Decisions", "Checked"]`).

| Heading                  | What goes there                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Purpose and requirements | What it is for, what it must do, its limits (loads, travel, sizes it must fit)                    |
| Decisions                | What was chosen, the alternatives left and why: a bronze nut, not a printed one, because it wears |
| Parameters               | What the main parameters mean and their safe ranges, by name (`railHeight`); never copy values    |
| Bought parts             | Standard and library parts, materials, where they come from                                       |
| Making it                | Print or machining settings, tolerances and fits                                                  |
| Checked                  | Interference, motion studies, mass: what passed, at which revision of which document              |
| Open questions           | What is not decided or not done yet                                                               |

Write short bullets of facts, with the revision a check was made at. Link a document with an ordinary Markdown link whose address is `moket:/d/<documentId>`: the preview shows the document's current name, so a rename breaks nothing. Never put secrets, tokens or personal data in a note.

## Changing a note

- `note.editSection` changes one section: `mode` `append` adds to the end of the section under `heading` (and adds the heading at the end of the note when it has none), `replace` replaces the section's text and keeps its heading. A heading matches by its text at any level, without case.
- `note.setText` replaces the whole text: use it only for a new note or when the user asks to rewrite one, and keep what was there.
- `document.rename` renames the note.

The plan's `changes` list the sections it adds, changes and removes, with the lines added and removed, and its `sections` give each one's text `before` and `after`. A plan applies at once unless the user approves changes: show the user what you wrote from `sections`, and to let them read it before it goes in, ask them to turn on Settings > Moket AI > Ask before applying AI changes with Any change checked (Changing what is in the part covers changed sections, not new ones). A note has no geometry, so nothing rebuilds.

```json plan:project-note
{
  "summary": "Keep what this session decided and checked",
  "steps": [
    {
      "label": "Decisions and checks",
      "commands": [
        {
          "type": "note.editSection",
          "heading": "Decisions",
          "text": "- Cross feed: Tr12x3 screw in a bronze nut (CuSn8): a printed nut wears out",
          "mode": "append"
        },
        {
          "type": "note.editSection",
          "heading": "Checked",
          "text": "- Interference of the lathe: none, 226 pairs (rev 30)\n- Motion study Cross feed: no collisions",
          "mode": "replace"
        }
      ]
    }
  ]
}
```