[@layout]: ../docs.layout.md

# Upgrade to PathMX 0.7

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.

[Jump to the copy/paste agent prompt](#agent-prompt).

---

## Choose the migration scope

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](../../releases/releases.changelog#pathmx-070-beta)
for the release scope. This guide targets 0.6.x projects; older projects should
also review the intervening release notes.

---

## 1. Preserve the running project

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.

---

## 2. Pin the installed packages

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](../packages.reference)
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.

---

## 3. Migrate custom code against the current contracts

| 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](../extend/plugins.reference#components),
[Plugin tutorial](../extend/plugins.guide), [Action reference](../extend/actions.reference),
and [Input reference](../authoring/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.

---

## 4. Preserve saved responses and sign-in state

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:

```yaml
# Before: legacy Input State properties
values:
  idea: Add a worked example.
submissions:
  reflection: "2026-09-24T14:00:00.000Z"
```

```yaml
# 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](../accounts/auth.reference#credential-changes-and-navigation) and
[State](../extend/state.reference). A package downgrade alone does not undo a
storage migration.

---

## 5. Verify before cutover

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](../hosting/deployment.reference) 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.

---

<!-- id: agent-prompt -->

## Copy this prompt into your coding agent

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.

```text
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.
```