@convesoft/mara 0.2.0 → 0.3.0

package/README.md

@@ -1,169 +1,68 @@
 # Mara
 
-Mara keeps project knowledge in readable Markdown while giving requirements,
-designs, decisions, and other durable facts stable identities, types, relations,
-validation, and deterministic retrieval. A CLI and stdio MCP server share the
-same operations, including discovery of narrative outside items.
+Mara keeps structured project knowledge in readable, Git-tracked Markdown.
+The CLI and stdio MCP server share authoring, retrieval, validation and
+traceability operations. Start with the [product documentation](docs/index.mara.md)
+and [Mara skill](skills/mara/SKILL.md).
 
-Mara 0.2.0 provides schema format 2 with flavour
-selection guidance, an engineering template, and unified `search`, `get`, and
-`related`. Start with the [0.2 migration guide](docs/migration-0.2.mara.md) for
-an existing project. The [0.1.0 documentation](https://github.com/convesoft/mara/tree/v0.1.0)
-describes the older released interface; use documentation and skill from the
-same revision as your executable.
+## Run
 
-## Run Mara
-
-Build the implementation described here with the pinned Rust toolchain:
+Build from this checkout with the pinned Rust toolchain:
 
 ```bash
 cargo build --locked --release
 ./target/release/mara --help
 ```
 
-The examples below use `mara` to mean this executable or an installed version
-that exposes the same interface. Register its absolute path for MCP. The
-checkout's version string alone does not establish which unreleased changes
-an older published prerelease includes; check its help and matching release
-notes before using the 0.2 workflow.
-
-Published npm packages contain prebuilt native binaries and use no install
-scripts or Rust toolchain. Run the stable 0.2.0 version:
+For a published release, replace `<version>` with its exact version:
 
 ```bash
-npx -y '@convesoft/mara@0.2.0' --version
-npx -y '@convesoft/mara@0.2.0' --help
-```
-
-Keep that exact pin in CLI and MCP launchers. Supported hosts are x64 and
-arm64 macOS, plus x64 and arm64 Linux compatible with Ubuntu 22.04's glibc
-baseline. Distribution guarantees are in
-[distribution and release](docs/distribution.mara.md).
-
-## Configure an MCP client
-
-For a client that starts stdio servers in the project directory:
-
-```toml
-[mcp_servers.mara]
-command = "/absolute/path/to/mara"
-args = ["mcp"]
-```
-
-To bind the server to one project regardless of its execution directory:
-
-```toml
-[mcp_servers.mara]
-command = "/absolute/path/to/mara"
-args = ["mcp", "--project", "/absolute/path/to/project"]
+npx -y '@convesoft/mara@<version>' --help
 ```
 
-For npm, use `command = "npx"` and prepend `"-y"` and
-`"@convesoft/mara@<version>"` to the arguments after substituting the exact pin.
-Without `--project`, project-bound tools accept an absolute `project` path or
-discover the nearest `.mara/project.toml` from the server's execution directory.
-A bound server rejects request-level project overrides; omit that parameter.
-
-## Configure Codex
-
-Register the executable and install [the Mara skill](skills/mara/SKILL.md)
-separately from the same checkout or release:
+The npm package runs a prebuilt binary without install scripts or a Rust toolchain.
+Supported platforms and package contents are defined in
+[distribution](docs/distribution.mara.md).
+For existing projects and clients, follow the [0.3 migration guide](docs/migration-0.3.mara.md).
 
-```bash
-codex mcp add mara -- /absolute/path/to/mara mcp
-```
+## Configure an agent
 
-Install the `skills/mara` directory through your client's skill installation
-workflow. Installing the skill does not install an executable; it reuses the
-configured MCP launcher for CLI fallback. For a published version, the npm
-package contains the matching skill as well as optional portable Agent Plugins
-1.0 metadata and MCP configuration.
+Configure your MCP client to launch `/absolute/path/to/mara` with arguments
+`["mcp", "--project", "/absolute/path/to/project"]`. For npm, launch `npx` with
+`["-y", "@convesoft/mara@<version>", "mcp", "--project", "/absolute/path/to/project"]`.
+Use the same exact version for CLI and MCP. A bound server uses that project;
+omit per-call project overrides.
 
-Compatible clients may install the complete package through the Convesoft
-marketplace as a convenience:
+Install the standalone skill separately from the matching checkout or extracted
+npm package:
 
 ```bash
-codex plugin marketplace add convesoft/mara
-codex plugin add mara@convesoft
+npx skills add /absolute/path/to/mara-package --skill mara
 ```
 
-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`.
+Select the intended agent and installation scope. The skill installer supports
+[local sources and skill selection](https://github.com/vercel-labs/skills#install-a-skill).
+Installing the skill does not install Mara; its CLI fallback reuses the configured
+MCP executable or exact npm pin.
 
-## Start authoring
+## Author knowledge
 
-Run this in a new project directory; `knowledge.mara.md` is created by the
-first item operation:
+In a new project directory, using `mara` for the selected executable:
 
 ```bash
 mara project init --template engineering
-mara schema list flavour
 mara schema get flavour requirement
-mara schema get relation verifies
 mara item create requirement REQ-ACCESS knowledge.mara.md \
-  --title "Permit access" --body "An authorized user can access the service."
-mara item create verification VER-ACCESS knowledge.mara.md \
-  --title "Check access" \
-  --body "Demonstrate that an authorized user can access the service." \
-  --relation verifies=REQ-ACCESS
+  --title 'Permit access' --body 'An authorized user can access the service.' \
+  --field status=draft
 mara project validate
-```
-
-`minimal` remains the default template; `empty` declares no vocabulary.
-`engineering` supplies engineering flavours and traceability relations.
-Templates create configuration and an editable schema only. Before creating an
-item, use the flavour's `description`, `use_when`, `avoid_when`, and
-`distinguish_from` to choose appropriate knowledge, then inspect its ID prefix,
-body, and field constraints. These guidance keys belong to the schema, not
-item metadata. See [guided authoring](docs/guided-authoring.mara.md) for the
-schema contract and engineering relation meanings.
-
-## Discovery and reading
-
-```bash
-mara --format json search "authorized user"
+mara --format json search 'authorized user'
 mara --format json get REQ-ACCESS
-mara --format json related REQ-ACCESS --direction incoming --relation verifies
-mara --format json get VER-ACCESS
-```
-
-CLI and MCP use `search`, `get`, and `related`; MCP get/related take
-`{"reference":"REQ-ACCESS"}`. Search returns mixed item, section, and Markdown
-block hits with one excerpt each. Pass a hit's `node.reference` to get or
-related, then read selected `connections[].neighbour.reference` values.
-`node.context.parent` identifies direct structural context. Documents and
-sections can be read and navigated without client filesystem access.
-
-Repeat a paginated call with its `next_cursor` until `has_more:false`, keeping
-all other inputs unchanged. Get returns consecutive content and ordered item
-metadata fragments; search excerpts are only for selection. Search and related
-accept `limit`; get does not. Item filters exclude narrative; project-relative
-path filters cover all search result kinds. For response fields, relation
-namespaces, containment, and handle lifetime, see
-[the discovery contract](docs/discovery.mara.md).
-
-Item authoring, list, and validation remain under `item`; relation mutations
-write schema-defined item edges. Mentions and containment derive from Markdown.
-Editing rejects changes that break or retarget surviving internal links; resolve
-reported impacts before retrying. See [item editing](docs/editing.mara.md) and
-[Markdown links and mutation safety](docs/discovery.mara.md#item-mutation-and-link-safety).
-Use `mara --help` or `mara <command> --help` for command and argument guidance.
-
-## Development
-
-```bash
-cargo fmt --all -- --check
-cargo clippy --locked --all-targets --all-features -- -D warnings
-cargo test --locked --all-targets
-cargo run --locked --quiet -- --format json project validate
-scripts/smoke-npm.sh target/release/mara
 ```
 
-See [the documentation index](docs/index.mara.md), [ROADMAP.md](ROADMAP.md),
-[AGENTS.md](AGENTS.md), and [SECURITY.md](SECURITY.md).
-
-## License
+Inspect the schema before choosing a flavour or relation. See
+[initialization and project context](docs/project.mara.md),
+[retrieval](docs/retrieval.mara.md), and [trace matrices](docs/traceability.mara.md)
+for their full contracts.
 
-Licensed under either [Apache License 2.0](LICENSE-APACHE) or the
-[MIT License](LICENSE-MIT), at your option.
+Licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).

package/bin/mara.cjs

@@ -8,7 +8,6 @@ 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"],
 ]);
 
@@ -18,7 +17,7 @@ const packageName = packages.get(platform);
 if (packageName === undefined) {
   console.error(
     `Mara does not provide a binary for ${process.platform}/${process.arch}. ` +
-      "Supported targets are glibc Linux and macOS on x64 or arm64.",
+      "Supported targets are glibc Linux on x64 or arm64, and Apple Silicon macOS.",
   );
   process.exitCode = 1;
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convesoft/mara",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Structured project knowledge CLI and MCP server",
   "author": "Aliaksei Raketski",
   "license": "MIT OR Apache-2.0",
@@ -18,16 +18,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@convesoft/mara-linux-x64-gnu": "0.2.0",
-    "@convesoft/mara-linux-arm64-gnu": "0.2.0",
-    "@convesoft/mara-darwin-x64": "0.2.0",
-    "@convesoft/mara-darwin-arm64": "0.2.0"
+    "@convesoft/mara-linux-x64-gnu": "0.3.0",
+    "@convesoft/mara-linux-arm64-gnu": "0.3.0",
+    "@convesoft/mara-darwin-arm64": "0.3.0"
   },
   "files": [
     "bin/mara.cjs",
-    "bin/mara-plugin.cjs",
-    "plugin.json",
-    "mcp.json",
     "skills/mara/SKILL.md",
     "README.md",
     "LICENSE-MIT",

package/skills/mara/SKILL.md

@@ -10,11 +10,14 @@ When MCP is unavailable, use an available Mara CLI invocation with `--format jso
 for structured results. The same operation selection, authoring, continuation,
 and validation rules apply to both surfaces.
 
-This skill targets the 0.2 interface: schema format 2 and unified `search`,
-`get`, and `related`. Use the skill shipped with the selected executable or
-the same source revision. If an older installation exposes a different
+This skill targets the current 0.3 development interface: schema format 3,
+discovery format 2, relationship format 1, validation format 1, and trace
+format 1. Typed inline relationships, inverse aliases, symmetric edges,
+external targets, graph policies, YAML current-state rules, and matrices are
+implemented. Use the skill shipped with the selected executable or
+the same source revision. If the selected installation exposes a different
 interface, report the mismatch and use its matching guidance; do not silently
-change the version pin or substitute removed commands.
+change the version pin or substitute unsupported commands.
 
 ## Resolve the CLI fallback
 
@@ -49,7 +52,9 @@ the MCP server was started with that root bound by `--project`. Use the default
 `minimal` template unless the user explicitly requests `empty` or `engineering`.
 Pass the selected name as `template` to `project_init`.
 `engineering` includes engineering flavours, selection guidance, and traceability
-relations; all templates generate configuration and schema only. The CLI equivalent
+relations. It also installs enabled `.mara/engineering-rules.yaml` and request-local
+`.mara/engineering-checks.yaml` and `.mara/engineering-execution.yaml`; no starter
+items are generated. The CLI equivalent
 is `"${mara_cli[@]}" --project /absolute/project --format json project init --template <template>`,
 where `<template>` is the selected `minimal`, `empty`, or `engineering` name.
 Do not create or modify `AGENTS.md` as part of Mara onboarding.
@@ -71,27 +76,44 @@ Use the selected project's declarations, including custom flavours. Keep
 supporting narrative as Markdown when it does not need an independent identity;
 search/get/related can still discover, read, and navigate it.
 
-Schema format 2 requires all four guidance keys directly on every flavour:
+Schema format 3 requires all four guidance keys directly on every flavour:
 a nonblank `description`, a nonempty list of nonblank `use_when` entries,
 an `avoid_when` list (`[]` is valid), and a `distinguish_from` mapping (`{}` is
 valid). Distinction targets must be other declared flavours with nonblank
-explanations. When asked to migrate format 1, edit the existing schema in place,
-set `format_version: 2`, and supply meaningful guidance. Preserve custom
-flavours, prefixes, fields, relations, document bytes, IDs, and MIDs; do not
+explanations. Edit the project schema in place with `format_version: 3` and
+meaningful guidance. Preserve custom flavours, prefixes, fields, relations,
+document bytes, IDs, and MIDs; do not
 reinitialize or replace the schema with a template. Require `valid:true` from
 both `schema_validate` and `project_validate` (CLI `schema validate` and
 `project validate`).
 
 For the engineering template, inspect `schema_get` relation declarations before
 connecting items. `verification` describes a repeatable check; `evidence`
-records its result. The added relations are `verifies` (verification →
+records its result. Engineering relations are `verifies` (verification →
 requirement/design), `validates` (verification → goal/scenario), `evidences`
-(evidence → verification), `implements` (artifact → requirement/design),
+(evidence → verification), `realizes` (artifact → requirement/design), code `implements`
+(→ requirement/design/verification) and code `checks` (→ requirement/design),
 `affects` (risk → affected knowledge), and `mitigates`
 (requirement/design/decision/verification → risk). Add only meaningful links;
 no complete trace chain or placeholder items are required. Existing projects
 do not gain these declarations automatically.
 
+New engineering items require `status`. Use `draft` while classifications and
+links are incomplete; `accepted` enables the bundled knowledge policies, and
+`retired` excludes an item from accepted coverage. Requirements
+and designs need `kind` when accepted; verification needs `method`, evidence needs
+`result`, `captured_at` and `subject_revision`, and risk needs `treatment`. Inspect
+the schema for enum values and optional fields. A status of accepted does not
+claim implementation or passing tests.
+
+Use `.mara/engineering-checks.yaml` with shape IRIs `urn:mara:rule:intent`,
+`urn:mara:rule:realization`, `urn:mara:rule:verification` or
+`urn:mara:rule:validation` on appropriate accepted roots. For execution, use
+`.mara/engineering-execution.yaml` with `urn:mara:rule:execution` on accepted
+verifications and bind `subject_revision` to the actual tested identity. This
+requires accepted evidence with `result: passed` at that revision; historical
+passing evidence and code associations do not establish a current execution result.
+
 ## Choose the operation
 
 CLI entries below follow `"${mara_cli[@]}" --project /absolute/project --format json`;
@@ -107,9 +129,39 @@ inspect `<command> --help` for positional arguments and options.
 | 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` |
+| Inspect an edge and its source occurrences | `relation_get` | `relation get SOURCE RELATION TARGET` |
 | 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` |
+| Inspect coverage for selected roots | `trace_matrix` | `trace matrix` |
+
+Validation (`project_validate`, `item_validate`, `schema_validate`) returns
+`valid`, `evaluation_complete`, `summary`, `diagnostics`, and output
+continuation. Match diagnostic `code` and `severity`, not message text.
+Warnings do not invalidate a complete result; configuration/source failures
+remain errors. Current-state rules load from explicit YAML files enabled by
+project format 2 and `[rules]` with `format_version = 1` and `files = [...]`.
+Run `schema_validate` to check definitions, then `project_validate` or
+`item_validate` to evaluate policy. Status/owner fields are project-defined.
+The engineering template supplies `status: draft|accepted|retired` and accepted-knowledge policies; existing
+projects gain no policies automatically. Schema relation `cardinality` and `acyclic` declarations impose structural graph policies when
+present. Policy failures do not block structured edits.
+Invalid schemas return the common envelope with `valid:false`, not an MCP
+tool error. Counts are null when the schema cannot load. Diagnostic `path` and
+`line` alias `location`; project-owned configuration paths are relative and
+unavailable coordinates are omitted.
+
+All three validation operations accept `limit` (1–100, default 20) and `cursor`;
+CLI uses `--limit` and `--cursor`.
+Continue unchanged inputs until `has_more:false`; summary
+and validity cover the full target before pagination and reporting paths.
+With configured rules, invalid corpus prerequisites skip policy evaluation,
+including item-targeted checks. Fix the original diagnostics and run validation
+again. `evaluation_unavailable` never means a policy pass. There is no logical
+work counter; finite shape/path restrictions and output pagination remain.
+Invalid arguments, stale cursors,
+I/O preventing a result, and oversized indivisible output return
+`{format_version:1,error:{code,message}}` with MCP `isError:true`.
 
 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
@@ -136,11 +188,12 @@ accept `limit`.
 
 Call `related` with `{"reference":"<selected reference>"}` for direct schema
 relations, mentions, and containment. It returns `node` and
-`connections:[{relation,direction,neighbour,source}]`; pass a selected
+`connections`; pass a selected
 `neighbour.reference` to `get` or another `related` call. Each call follows only
 direct connections; there is no automatic expansion or hops option.
 
-Use `direction:"incoming"` or `"outgoing"`; omission includes both. Related
+Use `direction:"incoming"`, `"outgoing"`, or `"symmetric"`; omission includes all.
+Direction is canonical even when a relation filter uses an inverse alias. Related
 `relations` accepts `schema:name` and `builtin:name`, with short names allowed
 only when unambiguous in the vocabulary. Related `flavours` selects item
 neighbours only. JSON represents containment as `contains` with direction;
@@ -161,9 +214,9 @@ Item MIDs retain durable identity. Search and related default to 20 entries
 and accept `limit` from 1 through 100; related counts connections, including
 different connections to the same neighbour. The byte budget may shorten pages.
 
-Unified discovery responses use `format_version: 1`, independently of schema
-format 2 and the application version. Inspect `node.kind` (item, section, block,
-or document); only items have ID/MID/flavour. Item list retains its item-only
+Unified discovery responses use `format_version: 2`, independently of schema
+format 3 and the application version. Inspect `node.kind` (item, section, block,
+document, or code); only items have ID/MID/flavour. Item list retains its item-only
 response. On upgrade, discard old cursors and update parsers for the mixed
 `results`, consecutive `content`, and `connections` shapes above.
 
@@ -173,6 +226,175 @@ then `"${mara_cli[@]}" --project /absolute/project --format json get '<reference
 Use `related '<reference>'` for connections, `--relation builtin:mentions` to
 select explicit mentions, and `--cursor '<next_cursor>'` for continuation.
 
+## Code endpoints
+
+Project format 3 uses one `[[code.languages]]` entry per integration with
+`name`, nonempty `extensions`, and `command` (executable/arguments, one standalone
+`{output}` placeholder). Extensions are case-sensitive suffixes without dots,
+unique across language entries. Mara invokes an indexer automatically from the
+project root only when unignored source files match its extensions. With no
+matches it skips that indexer, so empty projects can use documentation operations.
+Adding the first matching file activates indexing; removing the last skips it again.
+This applies with or without Tree-sitter and never suppresses failures once source
+files exist. Configuration and any declared grammar assets must still be valid;
+install indexers separately and only configure trusted commands. Commands may
+run build tools. Missing executables or invalid output fail the operation.
+Optional `position_encoding` supplies `utf8`, `utf16` or `utf32` for old indexers
+that omit their document encoding. The same entry may include `grammar` and
+`query` together for runtime Tree-sitter assets that attach comments
+and expand declaration content. Without these assets, symbol links still work;
+content uses the SCIP enclosing range, or the definition token when absent.
+Language integrations are supplied by the project.
+
+For example, with `rust-analyzer` installed and matching grammar assets present:
+
+```toml
+[[code.languages]]
+name = "rust"
+command = ["rust-analyzer", "scip", ".", "--output", "{output}"]
+position_encoding = "utf8"
+extensions = ["rs"]
+grammar = ".mara/code/rust.wasm"
+query = ".mara/code/rust.scm"
+```
+
+Omit `grammar` and `query` for SCIP-only use; keep `extensions`. Commands and paths are
+project-owned; Mara supplies no per-language defaults.
+
+Source markers use `@mara <canonical-relation> <item-ID-or-MID>` within captured
+comments. All markers in a leading comment group attach to the following
+supported declaration through its modifier/wrapper boundary. Ordinary/doc
+comments and blank lines may intervene; statements and lexical body boundaries
+stop attachment. Original marker spans and declaration content remain separate.
+Otherwise retain deepest-enclosing ownership, valid file fallback, or an
+unsupported/ambiguous-owner diagnostic. Inspect exact endpoints with `related`
+and `relation get`: validation alone also accepts unintended file links.
+
+Use exact `code:path::language::descriptor` references returned by navigation.
+Descriptors omit SCIP package metadata so version bumps preserve local links.
+Unsafe inline characters use uppercase UTF-8 percent escapes. Backticks remain
+literal: `` code:service.ts::typescript::`service.ts`/parse(). ``. Local SCIP symbols are
+unsupported. Distinct implementation overloads require distinct indexer identities;
+multiple declarations of one identity share a link. No name/position fallback is
+allowed. Renames/moves may break authored links. File-only `code:path` needs no
+language integration. See `docs/code-traceability.mara.md` in the Mara repository.
+
+## Inspect and change relationships
+
+Schema lookup accepts inverse aliases and returns the canonical declaration,
+`requested_name` and `inverse`. Lists show canonical names with aliases and
+symmetry. Alias endpoint validation exchanges source and target first.
+
+`related` returns each semantic schema edge once, with canonical `relation`,
+endpoint-facing `label`, `direction`, `neighbour`, `edge` and `occurrence_count`.
+Builtin connections retain `source`; use `relation_get` for schema locations.
+Symmetric edges are excluded by incoming/outgoing filters. Directed self-edges
+appear once as outgoing when direction is omitted. Different relation kinds
+remain distinct. Item-list/search filters still select items with authored
+metadata or inline assertions; canonical and alias filters select the same kind.
+
+`relation_get {source,relation,target,limit?,cursor?}` returns the canonical
+`edge`, total `occurrence_count` and a page of `occurrences`. Each occurrence
+retains its author, spelling, source location and opaque `reference` selector.
+Default limit is 20, maximum 100, with a 65,536-byte budget. Continue unchanged
+until `has_more:false`; re-inspect after source/schema changes.
+
+Add rejects an edge already asserted anywhere, including inverse, symmetric
+and inline ID/MID equivalents. Direct source may intentionally repeat assertions.
+`relation_remove {source,relation,target}` removes every occurrence across
+included files. Supply `occurrence` from inspection to remove exactly one.
+Stale or mismatched selectors fail without writes. Results report
+`changed_occurrences`, `remaining_occurrences` and `edge_exists`. Inline removal
+demotes internal `[[relation:target]]` to `[[target]]` and external assertions
+to Markdown autolinks, preserving surrounding prose. The retained internal
+mention still blocks deletion of its target.
+
+Author `[[relation:ID]]`, `[[relation:MID]]`, or
+`[[relation:external:https://host/path]]` in an item body using a canonical
+schema name or inverse alias. External targets require `external: true` on the
+relation declaration; Mara preserves their authored address and never fetches it.
+No whitespace, labels or nested markup is allowed
+inside the token. These assertions share metadata edge identity and produce no
+builtin mention. Code, raw contexts and escaped openings remain literal; typed
+tokens outside item bodies have no typed meaning. Unknown relations, malformed
+tokens and invalid targets in supported contexts fail validation. Use body
+creation/update to author inline assertions; relation add writes metadata.
+
+Before manually changing schema or relation vocabulary, read the source-edit
+workflow in `docs/schema-evolution.mara.md` in the Mara repository. Use the
+selected executable to inspect declarations and canonical edge occurrences,
+then run complete schema/project validation and consume all pages. Preserve a
+source checkpoint for manual recovery; `project_transaction_rollback` handles
+only a pending structured mutation journal.
+
+## Inspect trace coverage
+
+Use `trace_matrix` (CLI `trace matrix`) for a read-only view of selected roots.
+Select roots with `ids`, `flavours`, `fields`, `paths`, or `all:true`; pass either
+enabled rule IRIs in `rules` or a request-local `check:{files,shape,parameters?}`. CLI uses
+repeatable `--id`, `--flavour`, `--field KEY=VALUE`, `--path`, and either
+`--rule` or `--check-file` with `--shape`. Do not mix the two evaluation modes.
+The check files supply shapes for this request only; they do not enable policy
+for project validation. A named rule uses its own applicability and selection
+within the requested roots.
+
+For a reusable revision check, use a targetless root and an evidence shape in
+`rules/revision.yaml` (assuming the project declares these relations, flavours
+and evidence fields):
+
+```yaml
+- id: rule:revision_evidence
+  class: requirement
+  property:
+    - path: status
+      hasValue: accepted
+    - path: {inversePath: verifies}
+      qualifiedValueShape: rule:verified_revision
+      qualifiedMinCount: 1
+- id: rule:verified_revision
+  class: verification
+  property:
+    - path: status
+      hasValue: accepted
+    - path: {inversePath: evidences}
+      qualifiedValueShape: rule:passing_revision
+      qualifiedMinCount: 1
+- id: rule:passing_revision
+  class: evidence
+  property:
+    - path: status
+      hasValue: accepted
+    - path: result
+      hasValue: passed
+    - path: subject_revision
+      hasValue: {parameter: subject_revision}
+```
+
+Pass the concrete revision through CLI or MCP:
+
+```text
+mara trace matrix --id REQ-A --check-file rules/revision.yaml --shape urn:mara:rule:revision_evidence --param subject_revision=abc123
+trace_matrix {ids:["REQ-A"],check:{files:["rules/revision.yaml"],shape:"urn:mara:rule:revision_evidence",parameters:{subject_revision:"abc123"}}}
+```
+
+A placeholder may also be an entry in `in`.
+Values are exact text literals, including empty text; resolve Git refs before
+calling Mara. Missing, invalid, duplicate CLI, and unused bindings are errors.
+Keep the YAML unchanged across revisions. Read the resulting state and resolved
+literal in check explanations; this selects recorded evidence and neither runs
+a test nor proves its authenticity. Parameters do not apply to enabled rules.
+
+Read each result state (`passed`, `failed`, `not_applicable`, `unavailable`),
+the check and edge records, source locations, and per-evaluation `summaries`.
+An external endpoint is terminal; an edge outside root selection can still
+contribute to a check. Known rule failures are matrix data, while
+`evaluation_complete:false` means the view could not be fully evaluated.
+Continue with unchanged inputs and `next_cursor` until `has_more:false`;
+restart after source, schema, or rule changes. CLI defaults to Markdown for
+this command; `--format json` returns trace format 1. MCP returns JSON and
+accepts `render:"markdown"` for the matching Markdown page. The output is a
+projection, not a saved source of project knowledge.
+
 ## Preserve authored references
 
 Use `[[ID]]`/`[[MID]]` in item bodies or narrative for item mentions, and
@@ -204,7 +426,7 @@ The shared `:key: value` source syntax does not make these interchangeable:
 - **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.
+  source/target flavours first. Use canonical names or declared inverse aliases; reverse navigation is derived.
 
 CLI equivalents are `--title`, repeatable `--field KEY=VALUE`, update
 `--clear-field KEY`, and creation `--relation NAME=TARGET`. Never pass a relation

package/bin/mara-plugin.cjs

@@ -1,60 +0,0 @@
-#!/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

@@ -1,10 +0,0 @@
-{
-  "$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/plugin.json

@@ -1,19 +0,0 @@
-{
-  "$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.2.0"
-}