@convesoft/mara 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -14,9 +14,9 @@ baseline.
 Pin the exact version so an MCP restart cannot silently change behavior:
 
 ```bash
-npx -y @convesoft/mara@0.1.0-alpha.0 --version
-npx -y @convesoft/mara@0.1.0-alpha.0 project init ./example
-npx -y @convesoft/mara@0.1.0-alpha.0 --project ./example project validate
+npx -y @convesoft/mara@0.1.0-alpha.2 --version
+npx -y @convesoft/mara@0.1.0-alpha.2 project init ./example
+npx -y @convesoft/mara@0.1.0-alpha.2 --project ./example project validate
 ```
 
 The npm packages contain prebuilt native binaries and use no install scripts.
@@ -29,7 +29,7 @@ For a client that starts stdio servers in the project directory:
 ```toml
 [mcp_servers.mara]
 command = "npx"
-args = ["-y", "@convesoft/mara@0.1.0-alpha.0", "mcp"]
+args = ["-y", "@convesoft/mara@0.1.0-alpha.2", "mcp"]
 ```
 
 To bind the server to one project regardless of its execution directory, place
@@ -40,7 +40,7 @@ To bind the server to one project regardless of its execution directory, place
 command = "npx"
 args = [
   "-y",
-  "@convesoft/mara@0.1.0-alpha.0",
+  "@convesoft/mara@0.1.0-alpha.2",
   "mcp",
   "--project",
   "/absolute/path/to/project",
@@ -51,43 +51,37 @@ Without `--project`, the server can start anywhere. Project-bound tools accept
 an absolute `project` path or discover the nearest parent containing
 `.mara/project.toml` from the server's execution directory.
 
-## Agent Plugin package
+## Configure Codex
 
-The main npm package also contains a portable Agent Plugins 1.0 manifest, a
-Mara skill, and stdio MCP configuration. Compatible clients can install that
-package through their supported plugin distribution flow. Codex is the
-reference client; the portable package does not modify project `AGENTS.md`.
-
-Starting with `0.1.0-alpha.1`, a user without an existing Mara installation can
-install the complete package from the Convesoft Codex marketplace:
+Register the installed Mara executable as an MCP server and install the Mara
+skill separately:
 
 ```bash
-codex plugin marketplace add convesoft/mara
-codex plugin add mara@convesoft
+codex mcp add mara -- npx -y @convesoft/mara@0.1.0-alpha.2 mcp
+npx skills add convesoft/mara --skill mara -g -a codex
 ```
 
-Start a new Codex session after installation. Codex keeps an installed plugin
-snapshot in its managed cache. On first MCP start, its launcher uses `npx` to
-install and run that snapshot's exact Mara version with the matching native
-package in npm's cache.
-
-If Mara and its MCP server are already configured, install only the skill and
-keep using that existing executable:
+If Mara is already installed, register its absolute executable path instead:
 
 ```bash
-npx skills add convesoft/mara --skill mara -g -a codex
+codex mcp add mara -- /absolute/path/to/mara mcp
 ```
 
-For a new MCP registration backed by an existing installation, use the
-executable's absolute path:
+The skill and MCP server expose the same Mara operations without installing a
+second executable or depending on a client's plugin-cache layout.
+
+The npm package also contains an optional portable Agent Plugins 1.0 manifest,
+skill, and MCP configuration. Compatible clients may install the complete
+package through the Convesoft marketplace as a convenience:
 
 ```bash
-codex mcp add mara -- /absolute/path/to/mara mcp
+codex plugin marketplace add convesoft/mara
+codex plugin add mara@convesoft
 ```
 
-Use either the complete plugin or the existing-installation route. Do not add
-the complete plugin alongside an equivalent manually configured Mara MCP
-server.
+The complete plugin is not a release compatibility target. Do not install it
+alongside an equivalent manually configured Mara MCP server. Neither onboarding
+route modifies project `AGENTS.md`.
 
 ## Core workflow
 
@@ -104,8 +98,12 @@ mara item get REQ-EXAMPLE
 
 Run `mara --help` or `mara <object> <operation> --help` for the complete command
 surface. The canonical alpha behavior is documented in
-[`docs/alpha.mara.md`](docs/alpha.mara.md); distribution and release guarantees
-are in [`docs/distribution.mara.md`](docs/distribution.mara.md).
+[`docs/alpha.mara.md`](docs/alpha.mara.md). Structured update, move, rename,
+delete, and recovery follow [`docs/editing.mara.md`](docs/editing.mara.md).
+For existing projects whose items lack machine identities, run
+`mara project mid backfill`, then `mara project validate` before editing.
+Distribution and release guarantees are in
+[`docs/distribution.mara.md`](docs/distribution.mara.md).
 
 ## Development
 

package/bin/mara-plugin.cjs

@@ -29,7 +29,10 @@ const command = hasLocalRuntime ? process.execPath : "npx";
 const args = hasLocalRuntime
   ? [path.join(__dirname, "mara.cjs"), ...process.argv.slice(2)]
   : ["--yes", `${manifest.name}@${manifest.version}`, ...process.argv.slice(2)];
-const child = spawn(command, args, { stdio: "inherit" });
+const child = spawn(command, args, {
+  cwd: hasLocalRuntime ? undefined : path.parse(__dirname).root,
+  stdio: "inherit",
+});
 const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
 const forward = new Map();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Structured project knowledge CLI and MCP server",
   "author": "Aliaksei Raketski",
   "license": "MIT OR Apache-2.0",
@@ -18,10 +18,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.1",
-    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.1",
-    "@convesoft/mara-darwin-x64": "0.1.0-alpha.1",
-    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.1"
+    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.2",
+    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.2",
+    "@convesoft/mara-darwin-x64": "0.1.0-alpha.2",
+    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.2"
   },
   "files": [
     "bin/mara.cjs",

package/plugin.json

@@ -15,5 +15,5 @@
     "mcp",
     "agent-skill"
   ],
-  "version": "0.1.0-alpha.1"
+  "version": "0.1.0-alpha.2"
 }

package/skills/mara/SKILL.md

@@ -29,12 +29,18 @@ or modify `AGENTS.md` as part of Mara onboarding.
 1. Call `schema_get` before authoring unfamiliar flavours, fields, or relations.
 2. Use `item_search`, `item_list`, and `item_related` for bounded discovery;
    call `item_get` only for selected full items.
-3. Use `item_create`, `relation_add`, and `relation_remove` only when the user
-   has asked to change project knowledge.
+3. Use `item_create`, `item_update`, `item_move`, `item_rename`, `item_delete`,
+   `relation_add`, and `relation_remove` only when the user has asked to change
+   project knowledge.
 4. Run the narrowest relevant validation after a mutation and use
    `project_validate` when the requested work affects corpus-wide integrity.
 
 Mara source files remain canonical. Do not treat MCP results as a separate
-authoring store. Structured update, move, rename, and delete operations are not
-available yet; when one is required, edit the source file directly and validate
-the result.
+authoring store. Use `item_update` for partial title, custom-field, or body edits;
+use `item_move` to relocate an item while preserving identity. Update warnings
+about existing scaffold bodies still count as errors in explicit validation.
+Use `item_delete` to remove an item only when no surviving typed relations or
+supported wiki mentions refer to it; resolve reported blockers explicitly.
+Use `item_rename` to change a human ID and supported internal references while
+preserving the MID. Pending transactions block mutations; use
+`project_transaction_rollback` for explicit recovery after stopping other writers.