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

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.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
+npx -y @convesoft/mara@0.1.0-alpha.3 --version
+npx -y @convesoft/mara@0.1.0-alpha.3 project init ./example
+npx -y @convesoft/mara@0.1.0-alpha.3 --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.2", "mcp"]
+args = ["-y", "@convesoft/mara@0.1.0-alpha.3", "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.2",
+  "@convesoft/mara@0.1.0-alpha.3",
   "mcp",
   "--project",
   "/absolute/path/to/project",
@@ -57,7 +57,7 @@ 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
+codex mcp add mara -- npx -y @convesoft/mara@0.1.0-alpha.3 mcp
 npx skills add convesoft/mara --skill mara -g -a codex
 ```
 
@@ -100,6 +100,18 @@ 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). Structured update, move, rename,
 delete, and recovery follow [`docs/editing.mara.md`](docs/editing.mara.md).
+Search/list, `item related`, and `item get` return bounded pages; repeat the same
+command with `--cursor <next_cursor>` to continue. Get returns consecutive body
+and metadata fragments, then direct relations; follow continuation to retrieve
+the complete item. Inspect selected search passages with
+`mara item search "primary workflow" --id REQ-EXAMPLE --excerpts`.
+Search ranks exact matches before spelling corrections and favours ID/title
+matches. ID/MID field values use exact normalized words; item lookup and filters
+remain exact. Matching, bounds, continuation, and
+excerpts follow
+[`docs/retrieval.mara.md`](docs/retrieval.mara.md).
+Narrative outside item blocks remains accessible through file reads and file
+search; Mara MCP alone does not retrieve it.
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "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.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"
+    "@convesoft/mara-linux-x64-gnu": "0.1.0-alpha.3",
+    "@convesoft/mara-linux-arm64-gnu": "0.1.0-alpha.3",
+    "@convesoft/mara-darwin-x64": "0.1.0-alpha.3",
+    "@convesoft/mara-darwin-arm64": "0.1.0-alpha.3"
   },
   "files": [
     "bin/mara.cjs",

package/plugin.json

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

package/skills/mara/SKILL.md

@@ -5,8 +5,25 @@ description: Use Mara to initialize, discover, author, relate, retrieve, search,
 
 # Mara project knowledge
 
-Use the Mara MCP tools as the structured interface to a project's canonical
-`*.mara.md` knowledge.
+Prefer the Mara MCP tools for a project's canonical `*.mara.md` knowledge.
+When MCP is unavailable, use an available Mara CLI invocation with `--format json`
+for structured results. The same operation selection, authoring, continuation,
+and validation rules apply to both surfaces.
+
+## Resolve the CLI fallback
+
+Installing the skill does not install `mara` on PATH. Reuse the configured MCP
+launcher: keep its executable, runner arguments, exact package version, and
+environment; replace the `mcp` operation with the required CLI operation. Carry
+any bound project into the CLI's `--project` option.
+
+For the Bash examples below, put that launcher in an argument array `mara_cli`:
+`mara_cli=(npx -y '@convesoft/mara@<configured-version>')` (replace the placeholder
+with the existing exact pin), or `mara_cli=('/absolute/path/to/mara')` for a direct
+executable. Use `mara_cli=(mara)` only when `command -v mara` resolves it.
+Check `"${mara_cli[@]}" --version` and the operation's `--help`; preserve the pin
+and use only supported options. If no launcher is available, report the missing
+executable or runner rather than assuming a PATH installation or changing versions.
 
 ## Select the project
 
@@ -15,32 +32,155 @@ Use the Mara MCP tools as the structured interface to a project's canonical
   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.
+- For CLI calls, use `"${mara_cli[@]}" --project /absolute/project --format json ...`.
+  Without `--project`, the CLI discovers from its working 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.
+`minimal` template unless the user explicitly requests `empty`. The CLI equivalent
+is `"${mara_cli[@]}" --project /absolute/project --format json project init`.
+Do not create or modify `AGENTS.md` as part of Mara onboarding.
+
+## Choose the operation
+
+CLI entries below follow `"${mara_cli[@]}" --project /absolute/project --format json`;
+inspect `<object> <operation> --help` for positional arguments and options.
+
+| Intent | MCP operation | CLI command |
+|---|---|---|
+| Discover vocabulary and field/edge constraints | `schema_list`, then `schema_get`; omit kind/name for the full schema | `schema list`, `schema get` |
+| Find items by text or enumerate exact filters | `item_search` or `item_list` | `item search`, `item list` |
+| Read selected items, metadata, and direct relations | `item_get` | `item get` |
+| Inspect direct neighbours, then fetch selected bodies | `item_related`, then `item_get` | `item related`, then `item get` |
+| Create an item, optionally with initial edges | `item_create` | `item create` |
+| Change title, custom fields, or body | `item_update` | `item update` |
+| Relocate an item; preserve ID and MID | `item_move` | `item move` |
+| Change human ID and supported references; preserve MID | `item_rename` | `item rename` |
+| Add or remove an existing item's typed edge | `relation_add` or `relation_remove` | `relation add`, `relation remove` |
+| Delete an item; resolve reported relation/mention blockers | `item_delete` | `item delete` |
+| Check an item or whole-project integrity | `item_validate` or `project_validate` | `item validate`, `project validate` |
+
+Use mutations only when the user has asked to change project knowledge. Choose
+the structured mutation for the semantic change. An invalid-argument error calls
+for correcting the input or selecting the right operation; it is not a reason
+to bypass validation by editing source lines. Mara source files remain canonical;
+MCP results are not a separate authoring store.
+
+## Retrieve enough context
+
+For example, search with `{"query":"recovery","limit":5}`, select an ID from
+the results, and pass it to `item_get` and `item_related` as `id`. Use the project
+context selected above. Use `excerpts:true` on search when matching passages
+help selection; excerpts may skip content and do not replace an item read.
+
+Search, list, related, and get return `has_more` and `next_cursor`. When requested
+content is incomplete, repeat the same operation with that opaque `cursor`,
+keeping project, handle/query, filters, limit, and excerpt options unchanged.
+Continue until the needed content is retrieved; full enumeration/read requires
+`has_more:false`. Get can split body, metadata values, and relations across pages:
+use their byte/index ranges to reconstruct content, including complete titles.
+Restart without a cursor after source/schema changes. Related follows only direct
+edges; choose further neighbours explicitly.
+
+CLI retrieval uses the same JSON result fields: for example,
+`"${mara_cli[@]}" --project /absolute/project --format json item search recovery --limit 5`.
+Use `--cursor '<next_cursor>'` for continuation and `--excerpts` for passages.
+
+## Keep metadata inputs distinct
+
+Call `schema_get` before authoring unfamiliar flavours, fields, or relations.
+The shared `:key: value` source syntax does not make these interchangeable:
+
+- **Structural metadata:** pass title through `title`. Mara generates the
+  immutable MID; never supply, copy, or edit it. Creation `id` is a new human ID.
+- **Custom fields:** use `fields:[{"key":"...","value":"..."}]` only for
+  fields declared on that flavour. Supply required fields; repeat keys only
+  when allowed. Update replaces all values of each supplied key; use
+  `clear_fields` to remove optional keys. Omitted update values stay unchanged.
+- **Typed relations:** `justifies` and `satisfies` are relations, not custom
+  fields. `fields:[{"key":"justifies","value":"REQ-EXAMPLE"}]` is invalid.
+  Use creation `relations` or explicit relation operations; inspect allowed
+  source/target flavours first. Incoming backlinks are derived, never authored.
+
+CLI equivalents are `--title`, repeatable `--field KEY=VALUE`, update
+`--clear-field KEY`, and creation `--relation NAME=TARGET`. Never pass a relation
+through `--field`. CLI `--body -` reads stdin; MCP `body` is literal text.
+
+## Author and verify
+
+1. Inspect the schema and resolve existing targets with `item_get`. In this
+   example, the schema permits `decision` → `justifies` → `requirement`, and
+   `REQ-EXAMPLE` already exists. Replace `/absolute/project` with the selected root,
+   or omit `project` when the server is bound to it.
+2. Call `item_create` with a meaningful body and any required custom fields:
+
+```json
+{
+  "project": "/absolute/project",
+  "flavour": "decision",
+  "id": "ADR-EXAMPLE",
+  "file": "decisions.mara.md",
+  "title": "Keep edits recoverable",
+  "body": "Preserve the previous content until validation succeeds so rejected edits can be retried."
+}
+```
+
+3. Check `complete` and `missing`; a blank required body creates an incomplete
+   scaffold. Fill it with `item_update` before claiming completion.
+4. Call `relation_add` to add the edge:
+
+```json
+{
+  "project": "/absolute/project",
+  "source": "ADR-EXAMPLE",
+  "relation": "justifies",
+  "target": "REQ-EXAMPLE"
+}
+```
+
+When initial edges are already known, prefer adding
+`"relations":[{"relation":"justifies","target":"REQ-EXAMPLE"}]` to step 2
+instead of step 4. Creation validates and publishes the item and initial edges
+atomically, rejecting the whole request if an edge is invalid. Targets accept
+exact human IDs or MIDs. Do not add the same edge again; use `relation_add` and
+`relation_remove` for later changes (both take `source`, `relation`, `target`).
+
+5. Call `item_get` with `id:"ADR-EXAMPLE"`; inspect generated MID, title, body,
+   custom metadata, and outgoing relations. Call `item_related` with
+   `id:"ADR-EXAMPLE",direction:"outgoing"`, then with
+   `id:"REQ-EXAMPLE",direction:"incoming"` to verify both views of the edge.
+6. Call `item_validate` with `id:"ADR-EXAMPLE"`; use `project_validate` for
+   corpus-wide integrity after relation or reference changes. Use the same project
+   context. Require `valid:true`, not just successful transport. Project
+   validation `paths` filters reported diagnostics, not whole-project validity.
+
+Update warnings about existing scaffold bodies still count as errors in explicit
+validation. Pending transactions block mutations; use `project_transaction_rollback`
+(`project transaction rollback` in CLI) for explicit recovery after stopping
+other writers.
+
+For the same authoring workflow through CLI, after resolving `mara_cli` and
+`REQ-EXAMPLE`, use initial relations atomically when the selected version supports
+`--relation`, and inspect both directions:
+
+```bash
+mara_project=/absolute/project
+"${mara_cli[@]}" --project "$mara_project" --format json schema get
+"${mara_cli[@]}" --project "$mara_project" --format json item get REQ-EXAMPLE
+"${mara_cli[@]}" --project "$mara_project" --format json item create decision ADR-EXAMPLE decisions.mara.md \
+  --title 'Keep edits recoverable' \
+  --body 'Preserve the previous content until validation succeeds so rejected edits can be retried.' \
+  --relation justifies=REQ-EXAMPLE
+"${mara_cli[@]}" --project "$mara_project" --format json item get ADR-EXAMPLE
+"${mara_cli[@]}" --project "$mara_project" --format json item related ADR-EXAMPLE --direction outgoing
+"${mara_cli[@]}" --project "$mara_project" --format json item related REQ-EXAMPLE --direction incoming
+"${mara_cli[@]}" --project "$mara_project" --format json project validate
+```
+
+If the selected version lacks initial relations, or to use separate create/add,
+omit `--relation` during creation and then run
+`relation add ADR-EXAMPLE justifies REQ-EXAMPLE` with the same launcher and global
+project/JSON options. Check creation completeness and validation results as above.