fix: replace em dashes with standard punctuation in docs

[Mesut Oezdil (mesutoezdil)]

Em dashes (U+2014) are a common marker in AI-generated text. Replacing them with standard punctuation (colons, semicolons, commas) keeps the docs feeling hand-written and avoids the pattern being flagged by tools that detect AI-generated content.

Files changed:

• AGENTS.md
• docs/dev/code-layout.md
• docs/api-guide.md
• docs/architecture.md
• hack/microvm-assets/README.md

[Benjamin Elder (BenTheElder)]

Thanks for contributing but:

1. Em dashes are standard punctuation, that's where AI learned it from.
2. Not surprisingly, a project centered around AI uses AI quite a bit.

The sort of environment where AI generated content is "flagged" is probably not a likely user of substrate ...

[Mesut Oezdil (mesutoezdil)]

Thanks for contributing but:

1. Em dashes are standard punctuation, that's where AI learned it from.
2. Not surprisingly, a project centered around AI uses AI quite a bit.

The sort of environment where AI generated content is "flagged" is probably not a likely user of substrate ...

Before opening the PR, I had already thought about this as well. Fundamentally, I agree with your perspective.

That said, before LLM-generated outputs became widespread, how many reposs did we actually see these markers in? Or perhaps a better ques is: if sb is using these markers in 2026, people are likely to assume the code was written by an LLM.

If contributors opening a PR or issue are expected to follow the repo's "Using AI" guidelines, it could also encourage them to see the existing code as sth that was written by "humans".

But I can close the PR if needed. In the end, you can easily get 4 different opinions from 3 people on a topic like this. 🙂

[Benjamin Elder (BenTheElder)]

if sb is using these markers in 2026, people are likely to assume the code was written by an LLM.

The thing is, they would not be wrong. I don't think we should try to hide it. This repo is full of AI generated content.

If contributors opening a PR or issue are expected to follow the repo's "Using AI" guidelines, it could also encourage them to see the existing code as sth that was written by "humans".

Those guidelines do not say "don't use ai", very roughly they say "you are responsible as the human submitter to vet for quality, don't send us slop and don't blame the agent, don't enable rogue bot accounts without approval".

We want to work with other humans (e.g. when discussing designs) but we expect AI will be used to e.g. generate code. We have AGENTS.md and skills to support this.

[Benjamin Elder (BenTheElder)]

(Though, admittedly, we have let things get a little sloppy with some early tight timelines ... we're working on it)

[Mesut Oezdil (mesutoezdil)]

(Though, admittedly, we have let things get a little sloppy with some early tight timelines ... we're working on it)

Thank you; I’ll also open a PR for the things that caught my eye while reviewing the repo in detail.

Since everything is moving so fast, it’s certainly hard for you to keep track of everything.