Upgrade an existing project to 0.7.0 while preserving authored content, saved responses, and access rules. Use the checklist yourself, or copy the agent prompt below into your repository’s coding agent.
0.7.0 changes custom Plugin and Component authoring and saved Input response storage. Ordinary Markdown does not need a blanket rewrite. Inventory what your project actually uses before changing files.
| Your project uses | What to check |
|---|---|
| Official packages and authored content | Upgrade the installed release train together; lint and exercise the actual routes. |
| Local Plugins or Components | Migrate declarations, Action/Query callbacks, and renderer/client boundaries. |
| Saved Input responses | Inspect record shape and map old fields to their owning response Blocks. |
| Auth’s persistent storage | Back up its database; existing sessions and magic links can be invalidated by migration. |
| A writable deployment | Reconcile current live State at cutover; a development snapshot cannot replace newer user work. |
Read the 0.7.0 release notes for the release scope. This guide targets 0.6.x projects; older projects should also review the intervening release notes.
Record the current commit, package versions, lockfile, Bun version, launch command, and deployment configuration. Read the repository’s instructions and existing checks. Use a migration branch; use a separate worktree if work or deployment must continue on the current version. Uncommitted changes and ignored files do not follow a normal worktree automatically—identify what the migration needs.
Back up authored Sources, saved State, uploads, Auth storage, and other durable Plugin state. Keep secrets out of Git and diagnostic output. Run the migration preview against separate storage, including a separate state/database directory. Even starting a host or running a CLI check can initialize or migrate storage; a worktree is not isolation if its configuration still points to production.
If content changes during migration, reconcile those changes again after the project freezes. Keep the original application and its compatible State backup together for recovery.
Use stable Bun 1.4 or newer. In the project’s package.json, pin @pathmx/core
and every installed package in the official release train
to 0.7.0, keeping each dependency in its existing section. Do not add unused
Plugins or change unrelated third-party versions. Check custom Plugins’ framework
peer ranges and remove obsolete local tarball/workspace overrides from the deployable
manifest. Third-party Plugins need their own compatibility check.
Run bun install and commit the resulting lockfile with the migration. Run the
project’s installed CLI, normally bun run pmx, rather than a sibling framework
checkout. Updating the global launcher alone does not update a project’s pins.
| Area | 0.7 contract |
|---|---|
| Component declarations | Use defineComponent with an explicit tag, declared props, and explicit registration. Replace retired defineAppComponent declarations. |
| Static preparation | compile receives a named context and only handles this component’s declared tag. Declare staticProps for literal props used during compilation. |
| Authorized host reads | Use load({ props, compiled, view, source, page, block, app, signal, ... }); return selected JSON data. Use the admitted View for protected reads. |
| Presentation and clients | render({ props, compiled, data, slots }) renders that data. Link separate default-exported render/client modules with moduleRef. Keep host handles out of browser payloads. |
| Actions and Queries | Update callbacks to named context arguments. Preserve authorization, effect declarations, transaction behavior, and public action/query names. |
| Custom Input editors | Use input: true with a required string name prop bound to an existing field in the same Block. The client receives its scoped field handle. |
Use the complete examples in the Plugin reference, Plugin tutorial, Action reference, and Input reference. Read installed types when a callback’s exact shape is unclear. A search for old API names is an inventory, not permission for a mechanical find-and-replace. Preserve authored tags, routes, Block ids, field names, and domain behavior where the new contract supports them.
Input now stores values inside response records. A legacy Input State may contain
flat values and submissions maps. For example, when the authored reflection
Block owns the idea field, these relevant properties change as follows:
# Before: legacy Input State properties
values:
idea: Add a worked example.
submissions:
reflection: "2026-09-24T14:00:00.000Z"
# After: 0.7 Input State properties
responses:
reflection:
values:
idea: Add a worked example.
submittedAt: "2026-09-24T14:00:00.000Z"
This example omits the record’s identity and other metadata; preserve those
properties and its authored body. Determine ownership from the actual migrated
response definitions, not field order or the nearest heading. Preserve submission
timestamps; an unsubmitted response uses submittedAt: null. Records already in
the current format should remain unchanged. Update custom readers and tests that
still read flat values or old submission maps.
There is no universal pmx migrate command for this conversion. A project may
need a small converter matched to its Input definitions. It should preview changes
by default, archive exact originals before applying, report retired fields and
response ids, and make no changes on a second run. Duplicate possible owners,
mixed old/new formats, or missing Sources need explicit resolution. Never silently
drop historical answers or guess where they belong. Archive retired data and agree
on its treatment before changing active records.
Auth’s actor-binding migration preserves provider users but invalidates older sessions and magic links that cannot be safely bound. Test a fresh sign-in and sign-out with isolated storage and a test email destination. See Authentication and State. A package downgrade alone does not undo a storage migration.
Run the project’s existing check script, or its typecheck, tests, and installed
pmx lint separately when no combined script exists. Use --help for commands
that are unfamiliar; do not assume every repository defines check or a migration
script. Also exercise representative rendered routes and interactions:
- Anonymous and authenticated access, including denied cross-user access.
- Saved answers and completion before/after conversion, plus save, reload, and restart.
- Custom Components, Actions, Queries, uploads, and integrations the project uses.
- Unsaved drafts, keyboard focus, cursor position, and unaffected DOM during live updates.
- Mobile and keyboard interactions where the interface depends on them.
Retain concrete evidence and outstanding limitations. After the project freezes, reconcile latest code/content and fresh live State, then run the configured deployment preflight against the exact committed revision. Coordinate the final State conversion with stopping old-version writes. Never copy a rehearsal’s State over newer production records. Recovery must restore compatible application and storage versions and account for writes after cutover.
Run your agent in the existing project repository. The prompt asks it to complete the migration locally and produce a reviewable deployment handoff. It does not authorize production migration, deployment, or real email delivery.
Migrate this existing PathMX project to the published 0.7.0 beta release.
Preserve its content, domain behavior, saved user work, and access boundaries.
Complete the local migration and verification; do not stop after proposing a plan.
Read this guide and its linked current contracts first:
https://docs.pathmx.dev/docs/start/migrate-070.guide.md
Plugin API: https://docs.pathmx.dev/docs/extend/plugins.reference.md
Actions: https://docs.pathmx.dev/docs/extend/actions.reference.md
Input: https://docs.pathmx.dev/docs/authoring/input.reference.md
Auth: https://docs.pathmx.dev/docs/accounts/auth.reference.md
State: https://docs.pathmx.dev/docs/extend/state.reference.md
Deployment: https://docs.pathmx.dev/docs/hosting/deployment.reference.md
If a reference is unavailable, use the installed 0.7.0 types and report the gap;
do not invent replacement APIs or migration commands.
1. Read repository instructions. Inspect git status, current package pins,
lockfile, Bun version, scripts, custom Plugins, storage paths, and deployment
setup. Record a baseline and the checks that already pass or fail. Protect
uncommitted work. Use a migration branch; create a separate worktree if the
current checkout must remain usable. Account for needed uncommitted/ignored
files without copying secrets or production storage blindly.
2. Identify all durable Sources, Input State, uploads, Auth databases, and Plugin
state. Use isolated copies and a separate state/database directory for all
checks and preview servers. Do not boot 0.7 against live storage. Do not clear
browser drafts, rewrite production State, send real emails, or deploy.
3. Pin Core and every installed official release-train package to exactly 0.7.0.
Preserve dependency sections; inspect custom Plugin peer ranges. Remove stale
candidate tarball/workspace overrides from the deployable manifest. Run Bun
install and use this project's installed CLI. Do not add unused Plugins or
upgrade unrelated packages.
4. Migrate actual custom consumers to defineComponent, explicit registration,
declared props/staticProps, named Action/Query contexts, and moduleRef-linked
render/client modules. Keep authorized host reads in load and pass JSON data
to presentation. Preserve action effects/transactions and access rules. Bind
custom editors through the existing Input field contract. Keep stable tags,
routes, Block ids, and field names unless a specific incompatibility requires
a reviewed change. Remove superseded code rather than adding speculative shims.
5. Inspect saved Input records and custom readers. If legacy values/submissions
exist, map them to actual owning response Blocks in the migrated project.
Build a project-specific converter only if needed: preview by default, archive
originals before applying, preserve metadata/body/values/timestamps, report
retired data, reject ambiguous ownership or mixed formats, and prove rerunning
makes no changes. Never discard historical answers. Test Auth migration on a
copy and account for old sessions/links being invalidated.
6. Run the existing check script, or the applicable types/tests/lint commands.
Fix migration-caused failures. Exercise real browser routes with anonymous and
representative signed-in users: access denial, old saved work, save/reload,
restart, custom interactions, and draft/focus/DOM continuity on live update.
Check relevant mobile and keyboard flows. Keep synthetic writes isolated.
Report separately any inherited failures or behavior you could not verify.
7. Produce a concise migration handoff: versions and baseline commit, code and
State changes, verification results, exact preview/conversion commands, backup
locations, remaining decisions, and the production cutover/recovery sequence.
If work continued during migration, require a freeze and reconciliation with
latest main and fresh live State before cutover. Do not merge, push, deploy,
or apply production migrations without my separate instruction.
Make routine implementation decisions yourself. Ask only for concrete unresolved
product/API choices, ambiguous ownership or historical-data treatment, missing
access, or other blockers. Continue independent safe work while waiting. Do not
claim readiness solely because compilation or a homepage request succeeds.