docs(guide): correct ASCII framing, apm run stability, LSP discoverability

[Mohammed Alkindi (MohammedAlkindi)]

docs(guide): correct ASCII framing, apm run stability, LSP discoverability

TL;DR

The three corrections accepted on #2315. The report was filed against the v0.25
guide, so I re-verified each one against main at 0.28.0 first rather than
assuming they still held. All three do.

Closes #2315.

The three corrections, and how each was verified

1. ASCII was stated as a hard requirement. SKILL.md listed under Key rules:

• ASCII only: all CLI output and source must stay within printable ASCII

and troubleshooting.md extended that to "No emojis or unicode symbols."

APM handles UTF-8 package content fine. Compiling an instruction containing
# Cafe unicode with non-ASCII characters and an em dash round-tripped byte-correct
into CLAUDE.md. And APM's own audit draws the distinction the guide was missing:

$ apm audit --file .apm/instructions/utf8.instructions.md      # ordinary non-ASCII
[*] 1 file(s) scanned -- no issues found

$ apm audit --file .apm/instructions/hidden.instructions.md    # U+200B zero-width space
WARNING  ...  U+200B  Zero-width space
[!] 1 warning(s) in 1 file(s) -- hidden characters detected

So the rule is a portability recommendation, driven by consoles on a legacy code
page, not a parsing constraint. Reframed as such, and the troubleshooting row now
separates hidden characters from ordinary non-ASCII text instead of conflating them.

2. apm run reports itself as experimental; the guide did not.

$ apm run --help
Usage: apm run [OPTIONS] [SCRIPT_NAME]

  Run a script with parameters (experimental)

The command table described it as "Execute a named script" with no caveat, so
automation could reasonably treat the interface as stable. Labelled it, matching
the existing house style for experimental surfaces elsewhere in the same file.

I checked the two sibling commands rather than assuming: apm preview and
apm list do not report themselves as experimental, so they are deliberately
left alone.

3. LSP was missing from the overview. dependencies.md has a full "LSP
dependency formats" section and commands.md documents apm install driving LSP
phases, but SKILL.md neither activated on LSP nor mentioned it, so the skill
would not reliably engage on an LSP question. Added to the activation list and to
the dependencies reference line.

Scope

Five line edits across three files, no code changes.

The reporter explicitly excluded two adjacent claims as non-defects (singular
target: is valid, and LSP is documented outside the overview). I did not touch
either, and did not expand beyond the three accepted items.

Every added line is pure ASCII, checked mechanically -- it would be a poor look to
introduce non-ASCII into the paragraph explaining when non-ASCII is acceptable.
apm audit reports no issues on all three changed files.

No version bump: recent commits touching packages/apm-guide/ do not bump
packages/apm-guide/apm.yml, so I followed that.

How to check

$ apm run --help          # confirms the experimental label
$ apm audit --file <any file with ordinary non-ASCII>   # no issues

---

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

No tests added: this is a documentation-only change with no code paths involved,
and no test in the repo asserts on the guide's prose. The verification I did run
is quoted above.

Spec conformance (OpenAPM v0.1)

• N/A -- this PR does not change OpenAPM-observable behaviour.

Documentation only, and packages/apm-guide/ is not listed in
tests/spec_conformance/critical_paths.txt.

---

I used an AI coding assistant while preparing this change. I ran the apm run --help, UTF-8 compile, and apm audit checks quoted above myself against main
at 0.28.0, specifically to confirm the v0.25-era report had not gone stale. The
repository states no AI policy, so I am disclosing rather than assuming it does not
matter.

[Copilot]

Pull request overview

This PR updates the apm-usage guide skill docs to align the overview/troubleshooting guidance with current CLI behavior and existing detailed documentation, specifically around ASCII portability guidance, apm run stability, and LSP discoverability.

Changes:

• Reframes “ASCII-only” from a hard requirement to a portability recommendation, distinguishing ordinary UTF-8 content from hidden-character risks.
• Labels apm run as experimental in the command reference to match the CLI help text.
• Adds LSP to the skill activation cues and clarifies that the dependencies reference includes MCP and LSP server formats.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/apm-guide/.apm/skills/apm-usage/troubleshooting.md	Updates Windows encoding guidance to distinguish portability concerns from UTF-8 package content.
packages/apm-guide/.apm/skills/apm-usage/SKILL.md	Adds LSP to activation triggers and refines ASCII guidance / dependencies reference wording.
packages/apm-guide/.apm/skills/apm-usage/commands.md	Marks apm run as experimental in the scripts command table.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Mohammed Alkindi (MohammedAlkindi)]

You are right, that was over-stated. On a cp1252 console here U+00E9 and U+2014 encode fine and only characters outside the code page raise UnicodeEncodeError, so I have reworded it to say a non-ASCII character may fail depending on the active code page, with those codepoints as the concrete contrast. Ironically it was the same blanket framing this PR set out to correct. The rest of the row is unchanged.