Contributing command guides and resources

The command reference combines the live command registry with reviewed Markdown guides. A guide appears inside its command’s entry, before the collapsed automation syntax. You can improve one entry without rewriting the whole manual. The reference’s Practical guides list automatically links to every available guide; adding a guide does not require editing an index or Rust code.

Add or improve an entry

1. Find the command in the reference. Its ID is in Automation details.
2. Copy the guide template to docs/book/command-guides/<command-id>.md, or edit its existing file. For example, Extrude lives in solid.extrude.md.
3. Explain what the tool does, what must exist or be selected first, the dialog’s choices in a table, a short example, and useful DOs and DON’Ts. Use plain language rather than copying the raw automation parameters.
4. Add related commands and any checked community resources, then open a pull request. Documentation changes are reviewed like code.

Do not edit the generated src/reference/commands.md: rebuilding replaces it. The generator rejects guide filenames whose command is absent from the registry. Names, groups, shortcuts and automation parameters continue to come from that registry; handwritten explanations remain editable independently.

Use fourth-level headings (####) inside an entry so the command remains the parent section. Write image and page paths relative to the generated reference page, docs/book/src/reference/commands.md, not to the input guide file. For example, ../generated/sheet-metal.png and ../guide/sheet-metal.md.

Related commands

Write a command link as {{#command sheet.hem}}. The generator inserts its current name and links directly to that command. Unknown or missing command IDs and unfinished directives fail the book build, helping contributors catch stale links. Normal Markdown links can point to guide pages or external resources.

Community resources

You can add a focused tip, a short demo, a model or an illustrative screenshot to the entry’s resource table. Explain what the reader learns from each link; include author and licence information. Links are reviewed, not automatically collected from the web. A resource need not cover the whole command.

Use original SolidCraft examples or openly licensed resources with permission to share. Do not use designs, screenshots, help text or artwork extracted from commercial CAD products, or GPL/LGPL/AGPL code. Prefer small public-safe examples and remove private designs, paths and account information from evidence.

For a new file asset, follow assets/AGENTS.md and add its attribution in a new attribution/pending/<change>.md file. A reproducible recipe in docs/book/scripts/ can be rendered by the book builder; generated images stay out of Git. Existing examples demonstrate both inline pictures and resource links.

Preview and review

Run cargo xtask book with mdBook installed, inspect the command entry and its links, and check the example in SolidCraft. Confirm the required selection, units, defaults and limitations against the implementation. Show reviewers an actual before/after screenshot of the rendered entry. Repository quality gates still apply before a commit.

Copyable template

One sentence explaining what this command does and when someone would use it.

#### Before you start

- Explain the required body, sketch, region, edge, face or point in ordinary words.
- State whether a selection is required and what cannot be used instead.

#### Options

| Choice in the dialog | Meaning | Example or reason to choose it |
| --- | --- | --- |
| Replace with a real option | Explain the effect without copying parameter syntax. | A useful value with units. |

#### Try it

1. Start from a small reproducible design.
2. Name the selection, command, settings and expected visible result.

#### Tips and common mistakes

- **Do** explain a useful habit and its benefit.
- **Don't** describe an unsupported selection as if it worked.

#### Examples and community resources

Add only rows for resources you have checked. Replace placeholders before
submitting; do not publish an empty resource table.

| Kind | Resource and what it teaches | Author and licence |
| --- | --- | --- |
| Tip | Link to a focused explanation. | Credit and permission to reuse. |
| Demo | Link to a short recording or reproducible recipe. | Credit and licence. |
| Model | Link to an original SolidCraft design or an openly licensed model. | Credit and licence. |
| Screenshot | Link to or embed an actual SolidCraft result, with descriptive alternative text. | Credit and licence. |

#### See also

Use `{{#command solid.extrude}}` with a real related command's ID and explain
why it is related. The generator supplies its current label and a direct link.