Documentation

Read and search the project documentation, maintain the user documentation.

doc_read

effortless_doc_read — Stability: stable · project

Reads a blueprints/ document by path relative to the project root. Refuses any path outside blueprints/.

💬 You ask your agent

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

→ The agent callseffortless_doc_read

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

Name	Type	Required	Description
rel_path	string	yes	Path of the document relative to the project root. Required.

docs_list

effortless_docs_list — Stability: stable · project

Lists all Markdown documents under blueprints/ (recursive), with their title. Read-only.

💬 You ask your agent

« List the documents in blueprints/. »

→ The agent callseffortless_docs_list

No parameters.

docs_search

effortless_docs_search — Stability: stable · project

Full-text search (case- and accent-insensitive) in the blueprints/ documents, sorted by number of matches, with a snippet.

💬 You ask your agent

« Search for "authentication" in the blueprints/ documents. »

→ The agent callseffortless_docs_search

• query = authentication

Name	Type	Required	Description
query	string	yes	Full-text search term. Required.

i18n_apply

effortless_i18n_apply

Writes i18n translations into the user override (~/.effortless/locales/<surface>/<lang>.json) and marks keys machine (or human if reviewed=true). Never overwrites a human-reviewed entry unless reviewed. Flat keys. French forbidden (source).

💬 You ask your agent

« Apply these German translations to the interface: common.save becomes "Speichern" and common.cancel becomes "Abbrechen". »

→ The agent callseffortless_i18n_apply

• surface = front
• lang = de
• entries = {"common.save":"Speichern","common.cancel":"Abbrechen"}

Name	Type	Required	Description
surface	string	yes	Translation surface: front (user interface) or mcp (tool descriptions). Required.
lang	string	yes	Target language code (en, es, ru, …); never fr, which is the source. Required.
entries	object	yes	Translations as an object of flat keys to text (namespace.key for front, tools.<tool> for mcp). Required.
reviewed	boolean	no	If true, marks the entries as human-reviewed (protected from overwriting); default false marks them as machine translations.

i18n_export

effortless_i18n_export

Merged i18n catalog (embedded + user override) for a surface and language, as nested JSON.

💬 You ask your agent

« Export the interface's Spanish translation catalog. »

→ The agent callseffortless_i18n_export

• surface = front
• lang = es

Name	Type	Required	Description
surface	string	yes	Translation surface: front (user interface) or mcp (tool descriptions). Required.
lang	string	yes	Target language code (en, es, ru, …); fr is the source, so its delta is empty. Required.

i18n_status

effortless_i18n_status

Translation delta for an i18n surface (front|mcp) and language: keys missing vs the FR source (with their FR text) and unreviewed machine keys. Basis of the Agent-assisted translation flow.

💬 You ask your agent

« Which keys are missing from the interface's German translation? »

→ The agent callseffortless_i18n_status

• surface = front
• lang = de

Name	Type	Required	Description
surface	string	yes	Translation surface: front (user interface) or mcp (tool descriptions). Required.
lang	string	yes	Target language code (en, es, ru, …); fr is the source, so its delta is empty. Required.

project_docs_list

effortless_project_docs_list — Stability: stable · project

Lists the project framing documents: the files at the root of blueprints/ whose frontmatter carries type: cadrage-projet. Read-only.

💬 You ask your agent

« List the project's framing documents. »

→ The agent callseffortless_project_docs_list

No parameters.

user_doc_coverage

effortless_user_doc_coverage — Stability: beta · project

User documentation: coverage diagnosis (gap, outdated page, orphan page) and refusals (invalid inventory, impossible measurement, altered page). Two modes: observation (default) or publication.

💬 You ask your agent

« Run the coverage diagnosis on the site module's user documentation: gaps, outdated pages, orphan pages. »

→ The agent callseffortless_user_doc_coverage

• stack_id = site

Name	Type	Required	Description
stack_id	string	no	Id of the documentation stack (default: the only stack that declares user documentation).
regime	string	no	Coverage regime: observation (default) or publication.

user_doc_inventory

effortless_user_doc_inventory — Stability: beta · project

User documentation: reads and validates the declared inventory, resolving each source once. Refuses an invalid inventory (code 5) or an impossible measurement (code 6).

💬 You ask your agent

« Validate the user documentation inventory of the site module. »

→ The agent callseffortless_user_doc_inventory

• stack_id = site

Name	Type	Required	Description
stack_id	string	no	Id of the documentation stack (default: the only stack that declares user documentation).

user_doc_manifest

effortless_user_doc_manifest — Stability: beta · project

User documentation: closes an already produced build. Queries the version pair through the declared command, writes the manifest last in output_dir, and removes the whole output if it cannot produce it.

💬 You ask your agent

« The site module's documentation build is done in dist/docs: close it by writing its manifest. »

→ The agent callseffortless_user_doc_manifest

• stack_id = site
• output_dir = dist/docs

Name	Type	Required	Description
stack_id	string	no	Id of the documentation stack (default: the only stack that declares user documentation).
output_dir	string	yes	Build output directory, relative to the stack root; there is no default. Required.

user_doc_sync

effortless_user_doc_sync — Stability: beta · project

User documentation: installs an offline copy in the order write, verify, set aside, promote, remove. The candidate goes into staging_dir (a distinct location), its manifest is re-read there, and the format version is queried from the shell. A copy with a different format is refused and the existing copy is kept; staging on a different volume is refused before any action.

💬 You ask your agent

« Install the offline copy of the site module's documentation: the candidate is in dist/docs, staging in app/docs-staging, the current copy in app/docs. »

→ The agent callseffortless_user_doc_sync

• stack_id = site
• source_dir = dist/docs
• staging_dir = app/docs-staging
• current_dir = app/docs

Name	Type	Required	Description
stack_id	string	no	Id of the documentation stack (default: the only stack that declares user documentation).
source_dir	string	yes	Directory of the copy to install, relative to the stack root. Required.
staging_dir	string	yes	Staging directory, relative to the stack root; it must be distinct from the current copy and on the same storage. Required.
current_dir	string	yes	Directory of the current copy served by the shell, relative to the stack root. Required.