PathMX for agents

Start here when working in a PathMX repository. Identify the installed version, find the reference for your task, and verify changes using the project's own tools.

1. Read the local AGENTS.md and inspect existing changes before editing.
2. Check package.json, the lockfile, and installed @pathmx/* packages. These docs describe the current release; use installed types and command help to resolve version differences. Do not upgrade dependencies as a side effect.
3. Read the relevant reference below and a nearby working example. Reuse the project's existing components and conventions.
4. Make the change, run the project's checks, and preview affected routes. For interactive changes, check keyboard behavior, focus, and saved state. Report what changed, what passed, and anything still unverified.

Projects created with pmx init provide bun run pmx, bun run check, and bun run dev. Check the local scripts before running them. Use bun run pmx --help for installed commands, tree to locate Sources, and plugins list when Plugin configuration matters. After a coherent authoring change, run bun run pmx lint --format json; a clean result is [].

Check document.visibilityState when a scrolling check appears stuck. A hidden tab may stall smooth scrolling; use behavior: "instant" to verify its target, then check the visible interaction separately.

Read only what the task needs. These links return Markdown; resolve relative links against the URL of the document you fetched. If the topic is not listed, search the documentation index for its name and fetch the matching page.

Copy this into your task, or adapt it for your project's AGENTS.md:

Read https://docs.pathmx.dev/docs/agents before working in this
PathMX repository. Follow the repository's AGENTS.md, identify its
installed PathMX version, and fetch only the documentation relevant
to the task. Use https://docs.pathmx.dev/llms.txt to find additional
references. Verify changes with the project's installed commands
and preview affected pages.

Use the rendered page URL with a web-browsing tool. Some tools cannot read text/markdown; an unsupported-content-type error does not mean the page is missing. If the web reader fails and your agent has shell access, fetch the Markdown directly:

curl --fail --location --max-time 10 \
  -H 'Accept: text/markdown' https://docs.pathmx.dev/docs/agents

Keep the retrieved URL as evidence and report a failed web-reader attempt separately from a successful HTTP fallback. Access to private pages still requires the site's authentication and permissions.

/llms.txt lists public pages reachable from the homepage, with descriptions and direct Markdown links. Navigation, Source references, and public query results contribute to discovery. Unlinked pages remain readable when access permits, but are not listed.

Append .md to a page URL or request Accept: text/markdown:

curl https://docs.pathmx.dev/docs/authoring/callouts.reference.md
curl -H 'Accept: text/markdown' https://docs.pathmx.dev/docs/authoring/callouts.reference

HTML responses advertise the Markdown alternate through a Link header. /sitemap.xml lists canonical HTML URLs; /robots.txt names the sitemap. HTML pages declare their canonical URL without request query parameters. Unknown routes return 404, with recovery links for Markdown requests. See missing pages.

Use bun run pmx tree to locate Sources, query sources to inspect relationships, and perms to check access. The CLI reference owns the options; installed --help tells you which commands your release supports.

For example, in a project with a /docs folder:

bun run pmx query sources --from /docs --type reference --format table

For custom Plugin or loading changes, compare representative routes before and after using the project's performance tools. Routine prose edits do not need a performance audit.

Start with the Quickstart and its paths/about.md. The discovery commands above use the real public Docs site. Fetch the Callouts reference, then append this complete Block to your local paths/about.md:

---

## Before you arrive

> [!tip] Bring a question
> Choose one thing you would like to learn at the workshop.

Check and preview the edit:

bun run check
bun run dev

A clean check reports No issues found. Open /about.page: the tip appears under Before you arrive. Review its reading and Player sequence when Player is installed, then inspect git diff -- paths/about.md. This completes discover → fetch → edit → check without requiring private repository guidance.

For a rename, use PathMX's preview and receipt rather than manually leaving links behind. Run from the project root:

bun run pmx mv about.md getting-started.md --dry-run --format json
bun run pmx mv about.md getting-started.md --format json
bun run pmx lint --format json
git diff -- paths/

Keep pmx dev running: mv and rm automatically hand the operation to the local host. Paths are relative to the Source root, so use about.md, not paths/about.md. A failed handoff is not retried as a standalone write; inspect files before retrying after a lost response.

The preview contains exact before/after text; the successful write returns a compact receipt. Check the exit status before parsing: failed operations emit no JSON result. A clean JSON lint result is []. Follow an updated link and open /getting-started.page to verify the rename. Review any pre-existing edits in the diff before accepting your result.

pmx init creates a short, project-owned AGENTS.md with local commands, documentation guidance, and rendered verification. It also creates CLAUDE.md containing @AGENTS.md, so Claude Code imports the same instructions. Adapt AGENTS.md to your project. Initialization requires an empty directory and does not replace existing instructions.

The installed @pathmx/core package includes the optional pathmx-authoring skill. It covers educational content and practical guides: Source and Block identity, reuse, learning Paths, reading, Focus, Slides, response storage, and choosing a publishing target. It routes to the relevant documentation rather than embedding a second syntax manual. Detailed syntax stays in the references linked above. The skill is loaded when relevant rather than imported into startup instructions.

For Codex, copy the skill into the project's skill directory:

mkdir -p .agents/skills
cp -R node_modules/@pathmx/core/skills/pathmx-authoring .agents/skills/

For Claude Code, use its project skill directory:

mkdir -p .claude/skills
cp -R node_modules/@pathmx/core/skills/pathmx-authoring .claude/skills/

Choose the directory supported by your agent; other agents may use different locations. Review an existing skill before replacing it during an upgrade. Copying from the installed package keeps the starting skill aligned with that release. The generated project instructions also work without the skill.

• WebMCP for actions in a supported browser.
• Reuse content for following includes in delivered Markdown.
• CLI reference
• Authoring