Documentation

This path covers three things: reading your project's framing documentation, maintaining its user documentation (the one your users read), and translating the interface and the tool descriptions. You come to it to find a document, check that the documentation keeps up with the product, or add a language.

What you ask the agent

💬 You ask your agent

« Which framing documents does this project have? »

→ The agent callseffortless_docs_list

💬 You ask your agent

« Search the documentation for everything about delivery. »

→ The agent callseffortless_docs_search

• query = delivery

💬 You ask your agent

« Read me the document blueprints/012-Epic-Export/cadrage.md in full. »

→ The agent callseffortless_doc_read

• rel_path = blueprints/012-Epic-Export/cadrage.md

💬 You ask your agent

« Does our user documentation cover everything? Are there outdated pages? »

→ The agent callseffortless_user_doc_coverage

💬 You ask your agent

« Check the user documentation inventory. »

→ The agent callseffortless_user_doc_inventory

💬 You ask your agent

« The documentation build is done in dist/docs: write its manifest. »

→ The agent callseffortless_user_doc_manifest

• output_dir = dist/docs

💬 You ask your agent

« Install the new offline copy of the documentation: the candidate is in dist/docs, the staging copy in dist/staging, the current copy in app/docs. »

→ The agent callseffortless_user_doc_sync

• source_dir = dist/docs
• staging_dir = dist/staging
• current_dir = app/docs

💬 You ask your agent

« Which interface keys are not yet translated into Spanish? Translate them. »

→ The agent callseffortless_i18n_status

• surface = front
• lang = es

💬 You ask your agent

« Show me the English catalog of the tool descriptions. »

→ The agent callseffortless_i18n_export

• surface = mcp
• lang = en

What the agent does

Read and search the framing documentation

1. effortless_project_docs_list lists the project's framing documents: the files at the root of blueprints/ whose header carries type: cadrage-projet.
2. effortless_docs_list lists all the Markdown documents of blueprints/, subfolders included, with their title.
3. effortless_docs_search with query searches these documents, ignoring case and accents. Results are ranked by number of occurrences, each with an excerpt.
4. effortless_doc_read with rel_path (relative to the project root) reads a document. It refuses any path outside blueprints/.

These four verbs only read.

Maintain the user documentation

The user documentation is declared in a userdoc.json file at the root of a stack. All four verbs take stack_id; without it, the agent targets the only stack that declares user documentation.

1. effortless_user_doc_inventory reads and validates the declared inventory, and resolves each source once.
2. effortless_user_doc_coverage makes the diagnosis: gaps (a source nobody documents), outdated pages (the source has moved since generation), orphan pages (the source is gone). regime is observation (default: findings are returned without blocking) or publication (findings block).
3. effortless_user_doc_manifest with output_dir (relative to the stack, no default) closes a build already produced: it queries the version pair through the declared command and writes the manifest last. If it cannot produce it, it removes the whole output.
4. effortless_user_doc_sync with source_dir, staging_dir and current_dir installs an offline copy: the candidate is written to staging, its manifest is read back, and the format version is requested from the shell. A copy of a different format is refused and the copy in place is kept.

Translate the interface and the tool descriptions

Two surfaces can be translated: front (the interface) and mcp (the tool descriptions). French is the source; it is never written.

1. effortless_i18n_status with surface and lang returns the delta: the missing keys (with their French text) and the machine-translated keys no human has reviewed.
2. The agent translates this delta itself, then calls effortless_i18n_apply with entries (flat keys to text). The translations go to ~/.effortless/locales/<surface>/<lang>.json and are marked "machine". With reviewed: true, they are marked as reviewed by a human, and are no longer overwritten by a machine translation.
3. effortless_i18n_export returns the full catalog (shipped plus your additions) for a surface and a language, for inspection or backup.

What you get

• Documents found and read without you opening the blueprints/ folder. They can also be read in the Knowledge screen (framing lenses and search field).
• A coverage diagnosis with an exit code: conforming, gap, outdated, orphan, or one of the refusals (invalid inventory, measurement impossible, page altered).
• A build manifest and an installed offline copy, when you ask for them.
• Translation files in your home folder, without touching the shipped code.

When the agent is refused

Situation	What the refusal says	What to do
Path outside blueprints/, absolute or going up	"Chemin hors périmètre."	Give a relative path under blueprints/, as returned by effortless_docs_list.
No stack declares user documentation	userDoc:usage ("aucune stack ne porte de userdoc.json")	Declare a stack's user documentation.
Several stacks declare it	userDoc:usage (the stacks are named)	Pass stack_id.
Unknown stack_id	userDoc:usage	List the stacks with effortless_stack_list (see Code and stacks).
Invalid inventory (code 5)	userDoc:inventoryInvalid	Fix the inventory; effortless_user_doc_coverage names what is missing.
Measurement impossible (code 6)	userDoc:unmeasurable	A declared command failed: read it in the message and fix it.
Page altered (code 7)	userDoc:pageAltered	Regenerate the derived page rather than editing it by hand.
Blocking coverage under the publication regime	userDoc:coverageBlocking	Fill the coverage described in the report, or go back to observation.
Copy to install has a different format from the shell's	a userDoc:* refusal; the copy in place is kept	Rebuild the documentation with the right format version.
Invalid translation surface	"surface invalide … (attendu : front, mcp)"	Pass front or mcp.
Writing in French	"Le français est la source : écriture interdite."	Translate into another language (en, es, ru…).