@pathmx/path 0.5.0 → 0.5.1

package/README.md

@@ -1,30 +1,47 @@
 # `@pathmx/path`
 
-> This package is the current proof-of-concept implementation. The replacement
-> authoring and composition contract is being shaped in
-> [Path plugin](../../apps/pathmx-site/paths/work/path.design.md).
+Ordered learning-path semantics for PathMX applications. It recognizes
+`*.path.md` Sources and projects their linked lists into stable, nested steps.
 
-The Path semantic owner for the Paths product family. `PathPlugin` contributes
-the `path` Source schema; the same package projects viewer-readable Path
-Sources into ordered, nested steps with stable ids and guarded cycles.
+## Install
 
-Use the Plugin directly when composing a product without the full Paths preset:
+Add the package to an existing PathMX project:
+
+```sh
+bun run pmx plugins add path
+```
+
+Activate it with a repository Plugin:
 
 ```ts
+// plugins/path.plugin.ts
 export { default } from "@pathmx/path"
 ```
 
-`projectPath()` and `pathStepIds()` expose the Path structure to downstream
-systems. An unlabeled step derives its id from the href, so inserting Blocks
-does not orphan Completion; author `@step.<id>` when identity must survive a
-destination change. `rollupPathCompletion()` maps stable Path leaves onto a separately
-composed `@pathmx/completion` reader. `PathCompletionContributor` declares
-stable leaf `path/<step-id>` manual keys to the canonical Action; aggregate
-branches remain derived from their children:
+Most applications should install [`@pathmx/paths`](https://www.npmjs.com/package/@pathmx/paths)
+instead. That preset includes Path, Completion, and Player with the correct
+release versions.
 
-```ts
-CompletionPlugin({ contributors: [PathCompletionContributor] })
+## Author a Path
+
+Create a `*.path.md` Source whose unordered list links define the steps:
+
+```md
+# Web foundations
+
+- [Introduction](./introduction.md)
+- [HTML](./html.md)
+  - [Practice](./html-practice.md)
+- [CSS](./css.md)
+```
+
+Step ids are derived from their links. Give a step an explicit id when its
+identity must survive a destination change:
+
+```md
+- [@step.introduction Introduction](./welcome.md)
 ```
 
-`@pathmx/paths` supplies that composition. Completion is an optional peer;
-installing Path alone does not install or activate it.
+Plugin authors can use `projectPath()` to resolve a viewer-readable Path tree,
+`pathStepIds()` to inspect local step ids, and `rollupPathCompletion()` to
+combine a projected Path with a composed Completion reader.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pathmx/path",
   "description": "Ordered learning-path semantics for PathMX applications.",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "bun": ">=1.4.0"
   },
   "peerDependencies": {
-    "@pathmx/completion": "^0.5.0",
+    "@pathmx/completion": "^0.5.1",
     "@pathmx/core": "^0.5.0"
   },
   "peerDependenciesMeta": {