Documenting a project

mechabedo never writes a project's documentation itself. It asks a session to, and it can be asked in four ways, from the most guided to the most direct. All four read the same two things, so set those first.

What "as per the conventions set" means

A session documenting a project reads two sources, and both are yours to set:

• What the project is. AGENTS.md and .agents/knowledge/, written by the Conventions bootstrap or by hand. They are the authority; a session that documents from the code alone documents the implementation.
• What its documentation is. .agents/docs/projects.jsonl in the project itself, one line per thing it documents: one of four forms, the tool, where the sources live, how they build, and a note for the writer. It is edited on the Enhance page's Documentation row, and it lives in the checkout, so it travels with a clone and is reviewed with the code. With "Tell every session opened here" on, every session you start in that directory carries one paragraph saying exactly that.

A project with more than one thing to document declares a row each: a users' site, a separate landing page and an agent knowledge base are three readers, not one.

With both in place, a prompt needs only the starting point. Where a project declares nothing, a session documents in whatever form it finds or guesses, so declare it first: point the page at the directory, press Use what was found or add a row by hand, and save.

1. From the Documentation row

The most guided way, and the same shape as the bootstrap beside it. On the Documentation row, choose the target directory, pick a loadout, choose Set it up or Refresh what exists, add steering if you have any, and press Run. A session opens in the project on a new tab with a brief that states the manifest as the answer, names the knowledge chapters as the authority, and asks for one of the two scopes.

The right-hand column is the project's own manifest, one folded row each. The folder button on a row opens its sources in BedoIDE, and a project that declares nothing yet gets its manifest written by the run itself.

Use it to establish the documentation in the first place, or for a deliberate catch-up pass. The session ends when it is done and reports what it wrote and what the build said.

2. From a session's prompt line

Open a session in the project in AgentDeck, on any harness, and type the ask. The operation modes on the line decide how mechabedo stands behind it.

The first pass over a project:

Start documenting this project as per the conventions set, with the starting point being the README and .agents/knowledge/ /document /forever

What each part does:

• The sentence is the prompt. "As per the conventions set" points the session at AGENTS.md, the knowledge chapters and the manifest's note. "The starting point" names where to begin: the README, a knowledge chapter, a page of the site, a feature. Name one; the session reads outward from it.
• /forever keeps the pass going. Every finished turn is continued, including one that claims to be done, so a project too large for one turn is worked through. Nothing here is a terminal state: you end it, from the composer, which names the agents standing on the session and ends them on one click.
• /document stands the agent that, when a turn's work lands, brings the documentation up to date for exactly what that turn changed and touches nothing else. On a documenting session it is the review step: each turn's pages are held against the code they describe. Its real home is feature work, below.

The tokens come off the line wherever they are, and the two modes are one agent with two numbered duties, not two agents. The / menu offers every mode as you type, and the notice above the box says when an agent stands on the session.

Variants worth knowing:

Line	What happens
... /nohalt instead of /forever	The pass finishes on its own: when the session says it is done, the agent asks for a closing report and retires
... /tasklist /nohalt	The agent writes the list of pages first and hands them out one at a time, so a long pass has a visible remainder
Add CSV export to the report page /document /commit	Feature work: when it lands, the documentation follows the change, then one commit carries both
Refresh the documentation against the code; touch only what is wrong or missing /nohalt	A catch-up pass by hand, without the Enhance page

/document is the one to make a habit of. Armed on feature work, the documentation follows every user-facing change without anybody scheduling a documentation day; a turn that changed nothing a user sees earns no documentation turn.

3. From the bootstrap

A Conventions run asks the documentation question as part of the interview: none, markdown, a generated document, or a site, and the tool for the last two. Its answer is materialized last, after everything the documentation would describe, and AGENTS.md gets a paragraph saying where the documentation lives, how it builds, and that a user-facing change updates its page in the same change.

Its answer is written out as .agents/docs/projects.jsonl alongside the scaffold, which is where every later reader finds it. A project that already declares one answers the question in advance: the run's brief carries it, the session records it, and the interview does not ask it again.

4. From a workflow

Documented Shot is True Shot with /document armed on the dispatch: the interview on scope and shipping, one optimized prompt, this session works it, and when the work lands the documentation follows. Any workflow of your own gets the same by turning on Arm /document on its dispatch stage, which arms the mode over the origin session or over every agent of a fleet.

Keeping it current

Three things, and no schedule:

• The note in the brief, on by default for every declared row. It costs nothing and is worded to prevent churn: update the page a user-facing change touches, leave the documentation alone otherwise, run the build once when the sources were touched.
• /document on feature work, by hand or through a workflow.
• Refresh what exists on the Documentation row, when the documentation has drifted and you want one deliberate pass.

Which one when

Establishing: the Documentation row, or the prompt line with /forever or /tasklist /nohalt. Living with it: the note, and /document on the work that changes what users see.