[@layout]: ../docs.layout.md # 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. --- ## Start in the repository 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 `[]`. --- ## Verify scrolling in browser automation 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. --- ## Find the right reference 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](https://docs.pathmx.dev/llms.txt) for its name and fetch the matching page. | Task | Start with | | --- | --- | | Understand or create a project | [Methodology](../methodology.md), [Quickstart](../start/first-site.guide.md), [Project structure](../start/project-structure.guide.md) | | Write or reorganize content | [Blocks](../authoring/blocks.reference.md), [Markdown](../authoring/markdown.reference.md), [Links](../authoring/links.reference.md) | | Change layout or appearance | [Layouts](../site/layouts.reference.md), [Themes](../site/themes.reference.md), [Stylesheets](../site/styles.reference.md), [Components](../authoring/components.reference.md) | | Collect responses or run Actions | [Input](../authoring/input.reference.md), [Actions](../extend/actions.reference.md), [Personal state](../extend/state.reference.md) | | Build learning experiences | [Paths](../learning/path.reference.md), [Player](../learning/player.reference.md), [Completion](../learning/completion.reference.md) | | Configure sign-in | [Authentication](../accounts/auth.reference.md), [Email](../email.reference.md) | | Write or change a Plugin | [Plugin guide](../extend/plugins.guide.md), [Plugin API](../extend/plugins.reference.md), [Packages](../packages.reference.md) | | Inspect, check, or rename Sources | [CLI](../cli.reference.md) | | Publish a site | [Publish](../start/publish.guide.md), [Hosting](../hosting/index.md) | | Upgrade to 0.7 | [Migration guide and agent prompt](../start/migrate-070.guide.md#agent-prompt) | --- ## Give an agent this entry point Copy this into your task, or adapt it for your project's `AGENTS.md`: ```text 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. ``` --- ## Read a site as Markdown 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: ```sh 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](https://docs.pathmx.dev/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`: ```sh 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](../start/publish.guide.md#missing-pages). --- ## Inspect a project without a browser Use `bun run pmx tree` to locate Sources, `query sources` to inspect relationships, and `perms` to check access. The [CLI reference](../cli.reference.md) owns the options; installed `--help` tells you which commands your release supports. For example, in a project with a `/docs` folder: ```sh 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. --- ## Preview, edit, and verify Start with the [Quickstart](../start/first-site.guide.md) and its `paths/about.md`. The discovery commands above use the real public Docs site. Fetch the [Callouts reference](../authoring/callouts.reference.md), then append this complete Block to your local `paths/about.md`: ```md --- ## Before you arrive > [!tip] Bring a question > Choose one thing you would like to learn at the workshop. ``` Check and preview the edit: ```sh 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: ```sh 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. --- ## Project instructions and authoring skill `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: ```sh mkdir -p .agents/skills cp -R node_modules/@pathmx/core/skills/pathmx-authoring .agents/skills/ ``` For Claude Code, use its project skill directory: ```sh 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. --- ## Related - [WebMCP](../extend/webmcp.reference.md) for actions in a supported browser. - [Reuse content](../authoring/reuse-content.guide.md#check-reading-play-and-markdown) for following includes in delivered Markdown. - [CLI reference](../cli.reference.md) - [Authoring](../authoring/index.md)