@convesoft/mara 0.1.0-alpha.0 → 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,17 +29,59 @@ 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"]
 ```
 
-If the client starts elsewhere, add an explicit project root before `mcp`:
+To bind the server to one project regardless of its execution directory, place
+`--project` after `mcp`:
 
-```text
---project /absolute/path/to/project
+```toml
+[mcp_servers.mara]
+command = "npx"
+args = [
+  "-y",
+  "@convesoft/mara@0.1.0-alpha.2",
+  "mcp",
+  "--project",
+  "/absolute/path/to/project",
+]
+```
+
+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.
+
+## Configure Codex
+
+Register the installed Mara executable as an MCP server and install the Mara
+skill separately:
+
+```bash
+codex mcp add mara -- npx -y @convesoft/mara@0.1.0-alpha.2 mcp
+npx skills add convesoft/mara --skill mara -g -a codex
+```
+
+If Mara is already installed, register its absolute executable path instead:
+
+```bash
+codex mcp add mara -- /absolute/path/to/mara mcp
+```
+
+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 plugin marketplace add convesoft/mara
+codex plugin add mara@convesoft
 ```
 
-Mara discovers the nearest parent containing `.mara/project.toml` and binds one
-project when the MCP server starts.
+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
 
@@ -56,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

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const packages = new Map([
+  ["linux:x64", "@convesoft/mara-linux-x64-gnu"],
+  ["linux:arm64", "@convesoft/mara-linux-arm64-gnu"],
+  ["darwin:x64", "@convesoft/mara-darwin-x64"],
+  ["darwin:arm64", "@convesoft/mara-darwin-arm64"],
+]);
+
+const manifest = require("../package.json");
+const packageName = packages.get(`${process.platform}:${process.arch}`);
+let hasLocalRuntime = false;
+
+if (packageName !== undefined) {
+  try {
+    require.resolve(`${packageName}/package.json`);
+    hasLocalRuntime = true;
+  } catch {
+    // Codex extracts npm plugin packages without installing their dependencies.
+  }
+}
+
+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, {
+  cwd: hasLocalRuntime ? undefined : path.parse(__dirname).root,
+  stdio: "inherit",
+});
+const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+const forward = new Map();
+
+for (const signal of signals) {
+  const handler = () => child.kill(signal);
+  forward.set(signal, handler);
+  process.on(signal, handler);
+}
+
+child.once("error", (error) => {
+  console.error(`Could not start Mara from the Agent Plugin: ${error.message}`);
+  process.exitCode = 1;
+});
+
+child.once("exit", (code, signal) => {
+  for (const [name, handler] of forward) {
+    process.off(name, handler);
+  }
+
+  if (signal !== null) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code ?? 1;
+  }
+});

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "mara": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/bin/mara-plugin.cjs", "mcp"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Structured project knowledge CLI and MCP server",
   "author": "Aliaksei Raketski",
   "license": "MIT OR Apache-2.0",
@@ -18,13 +18,17 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.0",
-    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.0",
-    "@convesoft/mara-darwin-x64": "0.1.0-alpha.0",
-    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.0"
+    "@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",
+    "bin/mara-plugin.cjs",
+    "plugin.json",
+    "mcp.json",
+    "skills/mara/SKILL.md",
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE"

package/plugin.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "mara",
+  "description": "Discover, author, relate, and validate structured project knowledge.",
+  "author": {
+    "name": "Convesoft",
+    "url": "https://github.com/convesoft"
+  },
+  "homepage": "https://github.com/convesoft/mara",
+  "repository": "https://github.com/convesoft/mara",
+  "license": "MIT OR Apache-2.0",
+  "keywords": [
+    "project-knowledge",
+    "requirements",
+    "mcp",
+    "agent-skill"
+  ],
+  "version": "0.1.0-alpha.2"
+}

package/skills/mara/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mara
+description: Use Mara to initialize, discover, author, relate, retrieve, search, or validate structured project knowledge in Git-tracked *.mara.md files.
+---
+
+# Mara project knowledge
+
+Use the Mara MCP tools as the structured interface to a project's canonical
+`*.mara.md` knowledge.
+
+## Select the project
+
+- Resolve the intended project root to an absolute path.
+- Pass that path as `project` on every project-bound tool call unless the MCP
+  server was explicitly started with `mara mcp --project PATH`.
+- If `project` is omitted, Mara discovers the nearest project from the MCP
+  server's execution directory.
+- Treat each operation as scoped to one project. Do not infer workspace or
+  cross-project behavior.
+
+If the intended root has no `.mara/project.toml` and the user wants to start a
+Mara project, call `project_init` with the absolute root, or omit `project` when
+the MCP server was started with that root bound by `--project`. Use the default
+`minimal` template unless the user explicitly requests `empty`. Do not create
+or modify `AGENTS.md` as part of Mara onboarding.
+
+## Work with the corpus
+
+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`, `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. 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.