Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: write down the code-block file-name convention (#4177)

Maximilian Roosd72d0a95657d
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 88a49eeab..da253e20f 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -218,6 +218,15 @@ command parameters.
lines with `$ `; leave output unprefixed.
- Use the actual data language (`toml`, `json`, `yaml`, and so on) for files and
structured output.
+- Name the file a sample belongs in, as a first-line comment holding its path
+ (`# .config/wt.toml`, `# ~/.config/worktrunk/config.toml`, `# mise.toml`).
+ Expressive Code lifts it into the block's file-name tab and drops it from the
+ rendered code, while the committed Markdown keeps it as a readable comment.
+ Where a path comment would be invalid or noisy in the committed sample — a
+ `json` file, or a fenced `markdown` fragment — put `title="<path>"` on the
+ fence instead.
+ Blocks that show values for one key rather than a whole file, and
+ counter-examples, stay untitled; the prose says what they are.
Example:
@@ -241,6 +250,11 @@ conservative marker fallback. Generated Clap help fences carry the
option, value, and metadata roles. Committed Markdown must remain useful
without the plugin.
+Config samples inside the `USER_CONFIG_START` / `PROJECT_CONFIG_START` regions
+of `src/cli/mod.rs` carry no file-name comment: the double-comment rule under
+"Command-page generation" above already rules out the standalone comment line
+the path would need, and those sections name their file once at the top.
+
### Web-only post-processing
`post_process_for_html()` in `src/help.rs` handles the few semantic differences
diff --git a/docs/src/content/docs/llm-commits.md b/docs/src/content/docs/llm-commits.md
index e73408147..6b42b4cd2 100644
--- a/docs/src/content/docs/llm-commits.md
+++ b/docs/src/content/docs/llm-commits.md
@@ -40,6 +40,8 @@ Uses the fast, low-cost variant of the current Codex model family with low reaso
### Other tools
+Any of these replaces the `command` line above:
+
```toml
# opencode — use a fast model variant
command = "opencode run -m anthropic/claude-haiku-4.5 --variant fast"
diff --git a/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md b/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
index 1094399b4..2422e5e53 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
@@ -28,6 +28,8 @@ Uses the fast, low-cost variant of the current Codex model family with low reaso
### Other tools
+Any of these replaces the `command` line above:
+
```toml
# opencode — use a fast model variant
command = "opencode run -m anthropic/claude-haiku-4.5 --variant fast"
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index 1094399b4..2422e5e53 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -28,6 +28,8 @@ Uses the fast, low-cost variant of the current Codex model family with low reaso
### Other tools
+Any of these replaces the `command` line above:
+
```toml
# opencode — use a fast model variant
command = "opencode run -m anthropic/claude-haiku-4.5 --variant fast"