@convesoft/mara 0.1.0 → 0.2.0

package/README.md

@@ -2,25 +2,43 @@
 
 Mara keeps project knowledge in readable Markdown while giving requirements,
 designs, decisions, and other durable facts stable identities, types, relations,
-validation, and deterministic retrieval. The same operations are available as
-a CLI and a stdio MCP server.
+validation, and deterministic retrieval. A CLI and stdio MCP server share the
+same operations, including discovery of narrative outside items.
 
-Mara 0.1.0 provides the single-project CLI and MCP workflow. Supported hosts are x64 and
-arm64 macOS, plus x64 and arm64 Linux compatible with Ubuntu 22.04's glibc
-baseline.
+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 Mara
+
+Build the implementation described here with the pinned Rust toolchain:
+
+```bash
+cargo build --locked --release
+./target/release/mara --help
+```
 
-## Run with npx
+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.
 
-Pin the exact version so an MCP restart cannot silently change behavior:
+Published npm packages contain prebuilt native binaries and use no install
+scripts or Rust toolchain. Run the stable 0.2.0 version:
 
 ```bash
-npx -y @convesoft/mara@0.1.0 --version
-npx -y @convesoft/mara@0.1.0 project init ./example
-npx -y @convesoft/mara@0.1.0 --project ./example project validate
+npx -y '@convesoft/mara@0.2.0' --version
+npx -y '@convesoft/mara@0.2.0' --help
 ```
 
-The npm packages contain prebuilt native binaries and use no install scripts.
-A Rust toolchain is not required.
+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
 
@@ -28,51 +46,41 @@ For a client that starts stdio servers in the project directory:
 
 ```toml
 [mcp_servers.mara]
-command = "npx"
-args = ["-y", "@convesoft/mara@0.1.0", "mcp"]
+command = "/absolute/path/to/mara"
+args = ["mcp"]
 ```
 
-To bind the server to one project regardless of its execution directory, place
-`--project` after `mcp`:
+To bind the server to one project regardless of its execution directory:
 
 ```toml
 [mcp_servers.mara]
-command = "npx"
-args = [
-  "-y",
-  "@convesoft/mara@0.1.0",
-  "mcp",
-  "--project",
-  "/absolute/path/to/project",
-]
+command = "/absolute/path/to/mara"
+args = ["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.
+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 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 mcp
-npx skills add convesoft/mara --skill mara -g -a codex
-```
-
-If Mara is already installed, register its absolute executable path instead:
+Register the executable and install [the Mara skill](skills/mara/SKILL.md)
+separately from the same checkout or release:
 
 ```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.
+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.
 
-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:
+Compatible clients may install the complete package through the Convesoft
+marketplace as a convenience:
 
 ```bash
 codex plugin marketplace add convesoft/mara
@@ -83,54 +91,77 @@ 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
+## Start authoring
+
+Run this in a new project directory; `knowledge.mara.md` is created by the
+first item operation:
 
 ```bash
-mara project init
-mara schema get
-mara item create requirement REQ-EXAMPLE docs/example.mara.md \
-  --title "State one verifiable obligation" \
-  --body "The project must demonstrate its primary workflow."
+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
 mara project validate
-mara item search "primary workflow"
-mara item get REQ-EXAMPLE
 ```
 
-Run `mara --help` or `mara <object> <operation> --help` for the complete command
-surface. The core 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
-[`docs/distribution.mara.md`](docs/distribution.mara.md).
-The [stable 0.1 contract](docs/release-0.1.mara.md) records scope and limitations;
-[planned 0.2 changes](docs/guided-authoring.mara.md) are not part of this version.
+`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.
 
-## Development
+## Discovery and reading
+
+```bash
+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.
 
-The repository pins its Rust toolchain. From a checkout:
+## Development
 
 ```bash
-cargo test --locked --all-targets
+cargo fmt --all -- --check
 cargo clippy --locked --all-targets --all-features -- -D warnings
-cargo run -- --format json project validate
+cargo test --locked --all-targets
+cargo run --locked --quiet -- --format json project validate
+scripts/smoke-npm.sh target/release/mara
 ```
 
-See [`ROADMAP.md`](ROADMAP.md), [`AGENTS.md`](AGENTS.md), and
-[`SECURITY.md`](SECURITY.md).
+See [the documentation index](docs/index.mara.md), [ROADMAP.md](ROADMAP.md),
+[AGENTS.md](AGENTS.md), and [SECURITY.md](SECURITY.md).
 
 ## License
 

package/package.json

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

package/plugin.json

@@ -15,5 +15,5 @@
     "mcp",
     "agent-skill"
   ],
-  "version": "0.1.0"
+  "version": "0.2.0"
 }

package/skills/mara/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mara
-description: Use Mara to initialize, discover, author, relate, retrieve, search, or validate structured project knowledge in Git-tracked *.mara.md files.
+description: Use Mara to discover and read items and narrative, or author and validate structured project knowledge in Git-tracked *.mara.md files.
 ---
 
 # Mara project knowledge
@@ -10,6 +10,12 @@ 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
+interface, report the mismatch and use its matching guidance; do not silently
+change the version pin or substitute removed commands.
+
 ## Resolve the CLI fallback
 
 Installing the skill does not install `mara` on PATH. Reuse the configured MCP
@@ -40,21 +46,63 @@ executable or runner rather than assuming a PATH installation or changing versio
 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`. The CLI equivalent
-is `"${mara_cli[@]}" --project /absolute/project --format json project init`.
+`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
+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.
 
+## Choose vocabulary from the schema
+
+Call `schema_list` with `{"kind":"flavour"}`, then `schema_get` with
+`{"kind":"flavour","name":"requirement"}` for a candidate. CLI equivalents
+are `schema list flavour` and `schema get flavour requirement`.
+
+- `description` states purpose; `use_when` identifies suitable knowledge.
+- `avoid_when` excludes unsuitable content; `distinguish_from` compares
+  confusable flavours. Read the alternative declaration when the distinction
+  affects your choice.
+- `id_prefix`, `body`, and `fields` specify creation constraints. Guidance keys
+  belong to the schema declaration, not an item's `fields` or body.
+
+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:
+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
+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 →
+requirement/design), `validates` (verification → goal/scenario), `evidences`
+(evidence → verification), `implements` (artifact → 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.
+
 ## Choose the operation
 
 CLI entries below follow `"${mara_cli[@]}" --project /absolute/project --format json`;
-inspect `<object> <operation> --help` for positional arguments and options.
+inspect `<command> --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` |
+| Discover vocabulary and field/edge constraints | `schema_list` with kind, then `schema_get`; omit kind/name for the full schema | `schema list flavour` or `schema list relation`, then `schema get` |
+| Search items and narrative, or list items with exact filters | `search` or `item_list` | `search`, `item list` |
+| Read an item, section, Markdown block, or document | `get` | `get` |
+| Inspect direct connections from any node, then read a selected neighbour | `related`, then `get` | `related`, then `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` |
@@ -69,25 +117,78 @@ 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
+## Discovery and reading
+
+Call `search` with `{"query":"recovery","limit":5}`. Results contain
+`{node, excerpt}`; pass a selected `node.reference` to `get` as
+`{"reference":"<selected reference>"}`. Get also accepts exact item IDs/MIDs.
+Use the project context selected above. One source excerpt is included per search
+hit; it may omit content and does not replace a consecutive read. Item ID,
+flavour, custom-field, and schema-relation filters select items only; path
+filters also cover narrative. There is no node-kind filter.
 
-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.
+Get returns `node`, `content`, `content_range`, `metadata`, and `metadata_range`.
+Items return their parsed body and ordered metadata; other nodes return their
+original Markdown span, including contained source for sections and documents,
+with empty metadata. Read `node.context.parent` or `node.context.section` through
+get when structural context is needed. Get does not enumerate neighbours or
+accept `limit`.
 
-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.
+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
+`neighbour.reference` to `get` or another `related` call. Each call follows only
+direct connections; there is no automatic expansion or hops option.
 
-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.
+Use `direction:"incoming"` or `"outgoing"`; omission includes both. 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;
+human output displays its incoming view as `contained_by`. To find sibling
+context, inspect `related` with `relations:["builtin:contains"]` and
+`direction:"incoming"`, then select the parent's outgoing containment. Read
+chosen children with `get`.
+
+Search, item list, related, and get return `has_more` and `next_cursor`. Repeat
+the same operation with that opaque `cursor`, keeping project, reference/query,
+filters, and any supported limit unchanged. Continue until the needed content
+is retrieved; full enumeration/read requires `has_more:false`. Get splits
+consecutive content and metadata values across pages: use their byte/index
+ranges to reconstruct complete values, including titles and repeated metadata.
+Restart without a cursor after source/schema changes. Structural discovery
+handles identify source in a document snapshot; if stale, search again.
+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
+response. On upgrade, discard old cursors and update parsers for the mixed
+`results`, consecutive `content`, and `connections` shapes above.
+
+CLI retrieval uses the same JSON result fields:
+`"${mara_cli[@]}" --project /absolute/project --format json search recovery --limit 5`,
+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.
+
+## Preserve authored references
+
+Use `[[ID]]`/`[[MID]]` in item bodies or narrative for item mentions, and
+Markdown links for documents, heading sections, or explicit anchors, for example
+`[policy](./policies.mara.md#retry-policy)`. Resolve relative paths from the
+linking document. `mentions` and containment are derived; author them in
+Markdown, not with relation mutations. Code examples and escaped references
+remain literal. External URLs are not network-validated.
+
+Rename rewrites typed relation targets and supported wiki mentions in items and
+narrative, preserving MID. Create/update validate new internal references;
+create/update/move/delete reject changes that break or retarget surviving links,
+including generated anchors and links to nodes inside an item. Move can affect
+relative links. Delete can be blocked by references to contained sections or
+blocks. Resolve reported source locations before retrying; Markdown links are
+not automatically repaired. Do not bypass a rejected mutation with raw edits.
 
 ## Keep metadata inputs distinct
 
@@ -111,8 +212,8 @@ 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
+1. Inspect the schema and resolve existing targets with `get` using `reference`.
+   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:
@@ -148,10 +249,10 @@ 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.
+5. Call `get` with `reference:"ADR-EXAMPLE"`; inspect `node` for the generated
+   MID/title, `content` for the body, and `metadata` for authored values.
+   Call `related` with `reference:"ADR-EXAMPLE",direction:"outgoing"`, then with
+   `reference:"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
@@ -163,24 +264,18 @@ validation. Pending transactions block mutations; use `project_transaction_rollb
 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:
+`REQ-EXAMPLE`, use initial relations atomically 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 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 get ADR-EXAMPLE
+"${mara_cli[@]}" --project "$mara_project" --format json related ADR-EXAMPLE --direction outgoing
+"${mara_cli[@]}" --project "$mara_project" --format json 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.