[docs] docs: tighten markdown reference guidance

[github-actions]

Overview

Improves docs/src/content/docs/reference/markdown.md by trimming repetitive wording in the introductory guidance while preserving all examples, links, and security notes.

What changed

• condensed the intro to runtime-editable markdown instructions
• tightened the writing-guidance prose around specificity, action verbs, and failure handling
• simplified the content-organization and common-pitfalls sections without removing substantive guidance

Impact

• File improved: docs/src/content/docs/reference/markdown.md
• Bloat removed: verbose descriptions and repetitive phrasing
• Estimated reduction: modest wording cleanup across 4 sections with 6 lines changed

Validation

• make agent-report-progress-no-test failed because go build could not download the required Go toolchain from proxy.golang.org (Forbidden)

Notes

• Left unrelated existing worktree change in docs/src/content/docs/agent-factory-status.mdx untouched.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• pi.dev
• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pi.dev"
    - "proxy.golang.org"

See Network Configuration for more information.

🗜️ Compressed by Documentation Unbloat · gpt54 10.8 AIC · ⌖ 11.2 AIC · ⊞ 6.4K · ◷
_{Comment /unbloat to run again}

• expires on Jul 23, 2026, 5:00 PM UTC-08:00