@convesoft/mara 0.2.0-alpha.0 → 0.3.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -80
- package/package.json +5 -5
- package/plugin.json +1 -1
- package/skills/mara/SKILL.md +245 -40
package/README.md
CHANGED
|
@@ -2,28 +2,44 @@
|
|
|
2
2
|
|
|
3
3
|
Mara keeps project knowledge in readable Markdown while giving requirements,
|
|
4
4
|
designs, decisions, and other durable facts stable identities, types, relations,
|
|
5
|
-
validation, and deterministic retrieval.
|
|
6
|
-
|
|
5
|
+
validation, and deterministic retrieval. A CLI and stdio MCP server share the
|
|
6
|
+
same operations, including discovery of narrative outside items.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
and
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
8
|
+
This checkout adds typed inline relationships, metadata inverse aliases,
|
|
9
|
+
symmetric relationships, and occurrence inspection to the unified `search`,
|
|
10
|
+
`get`, and `related` workflow.
|
|
11
|
+
It requires schema format 3 and emits discovery format 2. Follow the
|
|
12
|
+
[relationship migration contract](docs/relations.mara.md) for existing projects.
|
|
13
|
+
Published 0.2.0 still uses schema format 2 and discovery format 1; use its
|
|
14
|
+
[documentation](https://github.com/convesoft/mara/tree/v0.2.0) and matching skill.
|
|
15
|
+
|
|
16
|
+
## Run Mara
|
|
17
|
+
|
|
18
|
+
Build the implementation described here with the pinned Rust toolchain:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
cargo build --locked --release
|
|
22
|
+
./target/release/mara --help
|
|
23
|
+
```
|
|
14
24
|
|
|
15
|
-
|
|
25
|
+
The examples below use `mara` to mean this executable or an installed version
|
|
26
|
+
that exposes the same interface. Register its absolute path for MCP. The
|
|
27
|
+
checkout's version string alone does not establish which unreleased changes
|
|
28
|
+
an older published prerelease includes; check its help and matching release
|
|
29
|
+
notes before using the 0.2 workflow.
|
|
16
30
|
|
|
17
|
-
|
|
31
|
+
Published npm packages contain prebuilt native binaries and use no install
|
|
32
|
+
scripts or Rust toolchain. Run the stable 0.2.0 version:
|
|
18
33
|
|
|
19
34
|
```bash
|
|
20
|
-
npx -y @convesoft/mara@0.
|
|
21
|
-
npx -y @convesoft/mara@0.
|
|
22
|
-
npx -y @convesoft/mara@0.1.0 --project ./example project validate
|
|
35
|
+
npx -y '@convesoft/mara@0.2.0' --version
|
|
36
|
+
npx -y '@convesoft/mara@0.2.0' --help
|
|
23
37
|
```
|
|
24
38
|
|
|
25
|
-
|
|
26
|
-
|
|
39
|
+
Keep that exact pin in CLI and MCP launchers. Supported hosts are x64 and
|
|
40
|
+
arm64 macOS, plus x64 and arm64 Linux compatible with Ubuntu 22.04's glibc
|
|
41
|
+
baseline. Distribution guarantees are in
|
|
42
|
+
[distribution and release](docs/distribution.mara.md).
|
|
27
43
|
|
|
28
44
|
## Configure an MCP client
|
|
29
45
|
|
|
@@ -31,51 +47,41 @@ For a client that starts stdio servers in the project directory:
|
|
|
31
47
|
|
|
32
48
|
```toml
|
|
33
49
|
[mcp_servers.mara]
|
|
34
|
-
command = "
|
|
35
|
-
args = ["
|
|
50
|
+
command = "/absolute/path/to/mara"
|
|
51
|
+
args = ["mcp"]
|
|
36
52
|
```
|
|
37
53
|
|
|
38
|
-
To bind the server to one project regardless of its execution directory
|
|
39
|
-
`--project` after `mcp`:
|
|
54
|
+
To bind the server to one project regardless of its execution directory:
|
|
40
55
|
|
|
41
56
|
```toml
|
|
42
57
|
[mcp_servers.mara]
|
|
43
|
-
command = "
|
|
44
|
-
args = [
|
|
45
|
-
"-y",
|
|
46
|
-
"@convesoft/mara@0.1.0",
|
|
47
|
-
"mcp",
|
|
48
|
-
"--project",
|
|
49
|
-
"/absolute/path/to/project",
|
|
50
|
-
]
|
|
58
|
+
command = "/absolute/path/to/mara"
|
|
59
|
+
args = ["mcp", "--project", "/absolute/path/to/project"]
|
|
51
60
|
```
|
|
52
61
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
62
|
+
For npm, use `command = "npx"` and prepend `"-y"` and
|
|
63
|
+
`"@convesoft/mara@<version>"` to the arguments after substituting the exact pin.
|
|
64
|
+
Without `--project`, project-bound tools accept an absolute `project` path or
|
|
65
|
+
discover the nearest `.mara/project.toml` from the server's execution directory.
|
|
66
|
+
A bound server rejects request-level project overrides; omit that parameter.
|
|
56
67
|
|
|
57
68
|
## Configure Codex
|
|
58
69
|
|
|
59
|
-
Register the
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
codex mcp add mara -- npx -y @convesoft/mara@0.1.0 mcp
|
|
64
|
-
npx skills add convesoft/mara --skill mara -g -a codex
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
If Mara is already installed, register its absolute executable path instead:
|
|
70
|
+
Register the executable and install [the Mara skill](skills/mara/SKILL.md)
|
|
71
|
+
separately from the same checkout or release:
|
|
68
72
|
|
|
69
73
|
```bash
|
|
70
74
|
codex mcp add mara -- /absolute/path/to/mara mcp
|
|
71
75
|
```
|
|
72
76
|
|
|
73
|
-
|
|
74
|
-
|
|
77
|
+
Install the `skills/mara` directory through your client's skill installation
|
|
78
|
+
workflow. Installing the skill does not install an executable; it reuses the
|
|
79
|
+
configured MCP launcher for CLI fallback. For a published version, the npm
|
|
80
|
+
package contains the matching skill as well as optional portable Agent Plugins
|
|
81
|
+
1.0 metadata and MCP configuration.
|
|
75
82
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
package through the Convesoft marketplace as a convenience:
|
|
83
|
+
Compatible clients may install the complete package through the Convesoft
|
|
84
|
+
marketplace as a convenience:
|
|
79
85
|
|
|
80
86
|
```bash
|
|
81
87
|
codex plugin marketplace add convesoft/mara
|
|
@@ -86,54 +92,77 @@ The complete plugin is not a release compatibility target. Do not install it
|
|
|
86
92
|
alongside an equivalent manually configured Mara MCP server. Neither onboarding
|
|
87
93
|
route modifies project `AGENTS.md`.
|
|
88
94
|
|
|
89
|
-
##
|
|
95
|
+
## Start authoring
|
|
96
|
+
|
|
97
|
+
Run this in a new project directory; `knowledge.mara.md` is created by the
|
|
98
|
+
first item operation:
|
|
90
99
|
|
|
91
100
|
```bash
|
|
92
|
-
mara project init
|
|
93
|
-
mara schema
|
|
94
|
-
mara
|
|
95
|
-
|
|
96
|
-
|
|
101
|
+
mara project init --template engineering
|
|
102
|
+
mara schema list flavour
|
|
103
|
+
mara schema get flavour requirement
|
|
104
|
+
mara schema get relation verifies
|
|
105
|
+
mara item create requirement REQ-ACCESS knowledge.mara.md \
|
|
106
|
+
--title "Permit access" --body "An authorized user can access the service."
|
|
107
|
+
mara item create verification VER-ACCESS knowledge.mara.md \
|
|
108
|
+
--title "Check access" \
|
|
109
|
+
--body "Demonstrate that an authorized user can access the service." \
|
|
110
|
+
--relation verifies=REQ-ACCESS
|
|
97
111
|
mara project validate
|
|
98
|
-
mara item search "primary workflow"
|
|
99
|
-
mara item get REQ-EXAMPLE
|
|
100
112
|
```
|
|
101
113
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
`mara item search "primary workflow" --id REQ-EXAMPLE --excerpts`.
|
|
111
|
-
Search ranks exact matches before spelling corrections and favours ID/title
|
|
112
|
-
matches. ID/MID field values use exact normalized words; item lookup and filters
|
|
113
|
-
remain exact. Matching, bounds, continuation, and
|
|
114
|
-
excerpts follow
|
|
115
|
-
[`docs/retrieval.mara.md`](docs/retrieval.mara.md).
|
|
116
|
-
Narrative outside item blocks remains accessible through file reads and file
|
|
117
|
-
search; Mara MCP alone does not retrieve it.
|
|
118
|
-
For existing projects whose items lack machine identities, run
|
|
119
|
-
`mara project mid backfill`, then `mara project validate` before editing.
|
|
120
|
-
Distribution and release guarantees are in
|
|
121
|
-
[`docs/distribution.mara.md`](docs/distribution.mara.md).
|
|
122
|
-
The [stable 0.1 contract](docs/release-0.1.mara.md) records scope and limitations;
|
|
123
|
-
[planned 0.2 changes](docs/guided-authoring.mara.md) are not part of this version.
|
|
114
|
+
`minimal` remains the default template; `empty` declares no vocabulary.
|
|
115
|
+
`engineering` supplies engineering flavours and traceability relations.
|
|
116
|
+
Templates create configuration and an editable schema only. Before creating an
|
|
117
|
+
item, use the flavour's `description`, `use_when`, `avoid_when`, and
|
|
118
|
+
`distinguish_from` to choose appropriate knowledge, then inspect its ID prefix,
|
|
119
|
+
body, and field constraints. These guidance keys belong to the schema, not
|
|
120
|
+
item metadata. See [guided authoring](docs/guided-authoring.mara.md) for the
|
|
121
|
+
schema contract and engineering relation meanings.
|
|
124
122
|
|
|
125
|
-
##
|
|
123
|
+
## Discovery and reading
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
mara --format json search "authorized user"
|
|
127
|
+
mara --format json get REQ-ACCESS
|
|
128
|
+
mara --format json related REQ-ACCESS --direction incoming --relation verifies
|
|
129
|
+
mara --format json get VER-ACCESS
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
CLI and MCP use `search`, `get`, and `related`; MCP get/related take
|
|
133
|
+
`{"reference":"REQ-ACCESS"}`. Search returns mixed item, section, and Markdown
|
|
134
|
+
block hits with one excerpt each. Pass a hit's `node.reference` to get or
|
|
135
|
+
related, then read selected `connections[].neighbour.reference` values.
|
|
136
|
+
`node.context.parent` identifies direct structural context. Documents and
|
|
137
|
+
sections can be read and navigated without client filesystem access.
|
|
138
|
+
|
|
139
|
+
Repeat a paginated call with its `next_cursor` until `has_more:false`, keeping
|
|
140
|
+
all other inputs unchanged. Get returns consecutive content and ordered item
|
|
141
|
+
metadata fragments; search excerpts are only for selection. Search and related
|
|
142
|
+
accept `limit`; get does not. Item filters exclude narrative; project-relative
|
|
143
|
+
path filters cover all search result kinds. For response fields, relation
|
|
144
|
+
namespaces, containment, and handle lifetime, see
|
|
145
|
+
[the discovery contract](docs/discovery.mara.md).
|
|
146
|
+
|
|
147
|
+
Item authoring, list, and validation remain under `item`; relation mutations
|
|
148
|
+
write schema-defined item edges. Mentions and containment derive from Markdown.
|
|
149
|
+
Editing rejects changes that break or retarget surviving internal links; resolve
|
|
150
|
+
reported impacts before retrying. See [item editing](docs/editing.mara.md) and
|
|
151
|
+
[Markdown links and mutation safety](docs/discovery.mara.md#item-mutation-and-link-safety).
|
|
152
|
+
Use `mara --help` or `mara <command> --help` for command and argument guidance.
|
|
126
153
|
|
|
127
|
-
|
|
154
|
+
## Development
|
|
128
155
|
|
|
129
156
|
```bash
|
|
130
|
-
cargo
|
|
157
|
+
cargo fmt --all -- --check
|
|
131
158
|
cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
132
|
-
cargo
|
|
159
|
+
cargo test --locked --all-targets
|
|
160
|
+
cargo run --locked --quiet -- --format json project validate
|
|
161
|
+
scripts/smoke-npm.sh target/release/mara
|
|
133
162
|
```
|
|
134
163
|
|
|
135
|
-
See [
|
|
136
|
-
[
|
|
164
|
+
See [the documentation index](docs/index.mara.md), [ROADMAP.md](ROADMAP.md),
|
|
165
|
+
[AGENTS.md](AGENTS.md), and [SECURITY.md](SECURITY.md).
|
|
137
166
|
|
|
138
167
|
## License
|
|
139
168
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@convesoft/mara",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0-alpha.0",
|
|
4
4
|
"description": "Structured project knowledge CLI and MCP server",
|
|
5
5
|
"author": "Aliaksei Raketski",
|
|
6
6
|
"license": "MIT OR Apache-2.0",
|
|
@@ -18,10 +18,10 @@
|
|
|
18
18
|
"node": ">=18"
|
|
19
19
|
},
|
|
20
20
|
"optionalDependencies": {
|
|
21
|
-
"@convesoft/mara-linux-x64-gnu": "0.
|
|
22
|
-
"@convesoft/mara-linux-arm64-gnu": "0.
|
|
23
|
-
"@convesoft/mara-darwin-x64": "0.
|
|
24
|
-
"@convesoft/mara-darwin-arm64": "0.
|
|
21
|
+
"@convesoft/mara-linux-x64-gnu": "0.3.0-alpha.0",
|
|
22
|
+
"@convesoft/mara-linux-arm64-gnu": "0.3.0-alpha.0",
|
|
23
|
+
"@convesoft/mara-darwin-x64": "0.3.0-alpha.0",
|
|
24
|
+
"@convesoft/mara-darwin-arm64": "0.3.0-alpha.0"
|
|
25
25
|
},
|
|
26
26
|
"files": [
|
|
27
27
|
"bin/mara.cjs",
|
package/plugin.json
CHANGED
package/skills/mara/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: mara
|
|
3
|
-
description: Use Mara to
|
|
3
|
+
description: Use Mara to discover and read items and narrative, or author and validate structured project knowledge in Git-tracked *.mara.md files.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Mara project knowledge
|
|
@@ -10,6 +10,15 @@ When MCP is unavailable, use an available Mara CLI invocation with `--format jso
|
|
|
10
10
|
for structured results. The same operation selection, authoring, continuation,
|
|
11
11
|
and validation rules apply to both surfaces.
|
|
12
12
|
|
|
13
|
+
This skill targets the current 0.3 development interface: schema format 3,
|
|
14
|
+
discovery format 2, relationship format 1, validation format 1, and trace
|
|
15
|
+
format 1. Typed inline relationships, inverse aliases, symmetric edges,
|
|
16
|
+
external targets, graph policies, YAML current-state rules, and matrices are
|
|
17
|
+
implemented. Use the skill shipped with the selected executable or
|
|
18
|
+
the same source revision. If an older installation exposes a different
|
|
19
|
+
interface, report the mismatch and use its matching guidance; do not silently
|
|
20
|
+
change the version pin or substitute removed commands.
|
|
21
|
+
|
|
13
22
|
## Resolve the CLI fallback
|
|
14
23
|
|
|
15
24
|
Installing the skill does not install `mara` on PATH. Reuse the configured MCP
|
|
@@ -48,24 +57,92 @@ is `"${mara_cli[@]}" --project /absolute/project --format json project init --te
|
|
|
48
57
|
where `<template>` is the selected `minimal`, `empty`, or `engineering` name.
|
|
49
58
|
Do not create or modify `AGENTS.md` as part of Mara onboarding.
|
|
50
59
|
|
|
60
|
+
## Choose vocabulary from the schema
|
|
61
|
+
|
|
62
|
+
Call `schema_list` with `{"kind":"flavour"}`, then `schema_get` with
|
|
63
|
+
`{"kind":"flavour","name":"requirement"}` for a candidate. CLI equivalents
|
|
64
|
+
are `schema list flavour` and `schema get flavour requirement`.
|
|
65
|
+
|
|
66
|
+
- `description` states purpose; `use_when` identifies suitable knowledge.
|
|
67
|
+
- `avoid_when` excludes unsuitable content; `distinguish_from` compares
|
|
68
|
+
confusable flavours. Read the alternative declaration when the distinction
|
|
69
|
+
affects your choice.
|
|
70
|
+
- `id_prefix`, `body`, and `fields` specify creation constraints. Guidance keys
|
|
71
|
+
belong to the schema declaration, not an item's `fields` or body.
|
|
72
|
+
|
|
73
|
+
Use the selected project's declarations, including custom flavours. Keep
|
|
74
|
+
supporting narrative as Markdown when it does not need an independent identity;
|
|
75
|
+
search/get/related can still discover, read, and navigate it.
|
|
76
|
+
|
|
77
|
+
Schema format 3 retains all four guidance keys directly on every flavour:
|
|
78
|
+
a nonblank `description`, a nonempty list of nonblank `use_when` entries,
|
|
79
|
+
an `avoid_when` list (`[]` is valid), and a `distinguish_from` mapping (`{}` is
|
|
80
|
+
valid). Distinction targets must be other declared flavours with nonblank
|
|
81
|
+
explanations. When asked to migrate format 1, edit the existing schema in place,
|
|
82
|
+
set `format_version: 3`, and supply meaningful guidance. Preserve custom
|
|
83
|
+
flavours, prefixes, fields, relations, document bytes, IDs, and MIDs; do not
|
|
84
|
+
reinitialize or replace the schema with a template. Require `valid:true` from
|
|
85
|
+
both `schema_validate` and `project_validate` (CLI `schema validate` and
|
|
86
|
+
`project validate`).
|
|
87
|
+
|
|
88
|
+
For the engineering template, inspect `schema_get` relation declarations before
|
|
89
|
+
connecting items. `verification` describes a repeatable check; `evidence`
|
|
90
|
+
records its result. The added relations are `verifies` (verification →
|
|
91
|
+
requirement/design), `validates` (verification → goal/scenario), `evidences`
|
|
92
|
+
(evidence → verification), `implements` (artifact → requirement/design),
|
|
93
|
+
`affects` (risk → affected knowledge), and `mitigates`
|
|
94
|
+
(requirement/design/decision/verification → risk). Add only meaningful links;
|
|
95
|
+
no complete trace chain or placeholder items are required. Existing projects
|
|
96
|
+
do not gain these declarations automatically.
|
|
97
|
+
|
|
51
98
|
## Choose the operation
|
|
52
99
|
|
|
53
100
|
CLI entries below follow `"${mara_cli[@]}" --project /absolute/project --format json`;
|
|
54
|
-
inspect `<
|
|
101
|
+
inspect `<command> --help` for positional arguments and options.
|
|
55
102
|
|
|
56
103
|
| Intent | MCP operation | CLI command |
|
|
57
104
|
|---|---|---|
|
|
58
|
-
| Discover vocabulary and field/edge constraints | `schema_list
|
|
59
|
-
|
|
|
60
|
-
| Read
|
|
61
|
-
| Inspect direct
|
|
105
|
+
| 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` |
|
|
106
|
+
| Search items and narrative, or list items with exact filters | `search` or `item_list` | `search`, `item list` |
|
|
107
|
+
| Read an item, section, Markdown block, or document | `get` | `get` |
|
|
108
|
+
| Inspect direct connections from any node, then read a selected neighbour | `related`, then `get` | `related`, then `get` |
|
|
62
109
|
| Create an item, optionally with initial edges | `item_create` | `item create` |
|
|
63
110
|
| Change title, custom fields, or body | `item_update` | `item update` |
|
|
64
111
|
| Relocate an item; preserve ID and MID | `item_move` | `item move` |
|
|
65
112
|
| Change human ID and supported references; preserve MID | `item_rename` | `item rename` |
|
|
113
|
+
| Inspect an edge and its source occurrences | `relation_get` | `relation get SOURCE RELATION TARGET` |
|
|
66
114
|
| Add or remove an existing item's typed edge | `relation_add` or `relation_remove` | `relation add`, `relation remove` |
|
|
67
115
|
| Delete an item; resolve reported relation/mention blockers | `item_delete` | `item delete` |
|
|
68
116
|
| Check an item or whole-project integrity | `item_validate` or `project_validate` | `item validate`, `project validate` |
|
|
117
|
+
| Inspect coverage for selected roots | `trace_matrix` | `trace matrix` |
|
|
118
|
+
|
|
119
|
+
Validation (`project_validate`, `item_validate`, `schema_validate`) returns
|
|
120
|
+
`valid`, `evaluation_complete`, `summary`, `diagnostics`, and output
|
|
121
|
+
continuation. Match diagnostic `code` and `severity`, not message text.
|
|
122
|
+
Warnings do not invalidate a complete result; configuration/source failures
|
|
123
|
+
remain errors. Current-state rules load from explicit YAML files enabled by
|
|
124
|
+
project format 2 and `[rules]` with `format_version = 1` and `files = [...]`.
|
|
125
|
+
Run `schema_validate` to check definitions, then `project_validate` or
|
|
126
|
+
`item_validate` to evaluate policy. Status/owner fields are project-defined;
|
|
127
|
+
templates and existing projects gain no policies automatically. Schema relation
|
|
128
|
+
`cardinality` and `acyclic` declarations impose structural graph policies when
|
|
129
|
+
present. Policy failures do not block structured edits.
|
|
130
|
+
Invalid schemas now return the common envelope with `valid:false`, not an MCP
|
|
131
|
+
tool error. Counts are null when the schema cannot load. Diagnostic `path` and
|
|
132
|
+
`line` alias `location`; project-owned configuration paths are relative and
|
|
133
|
+
unavailable coordinates are omitted.
|
|
134
|
+
|
|
135
|
+
All three validation operations accept `limit` (1–100, default 20) and `cursor`;
|
|
136
|
+
CLI uses `--limit` and `--cursor`.
|
|
137
|
+
Continue unchanged inputs until `has_more:false`; summary
|
|
138
|
+
and validity cover the full target before pagination and reporting paths.
|
|
139
|
+
With configured rules, invalid corpus prerequisites skip policy evaluation,
|
|
140
|
+
including item-targeted checks. Fix the original diagnostics and run validation
|
|
141
|
+
again. `evaluation_unavailable` never means a policy pass. There is no logical
|
|
142
|
+
work counter; finite shape/path restrictions and output pagination remain.
|
|
143
|
+
Invalid arguments, stale cursors,
|
|
144
|
+
I/O preventing a result, and oversized indivisible output return
|
|
145
|
+
`{format_version:1,error:{code,message}}` with MCP `isError:true`.
|
|
69
146
|
|
|
70
147
|
Use mutations only when the user has asked to change project knowledge. Choose
|
|
71
148
|
the structured mutation for the semantic change. An invalid-argument error calls
|
|
@@ -73,25 +150,159 @@ for correcting the input or selecting the right operation; it is not a reason
|
|
|
73
150
|
to bypass validation by editing source lines. Mara source files remain canonical;
|
|
74
151
|
MCP results are not a separate authoring store.
|
|
75
152
|
|
|
76
|
-
##
|
|
153
|
+
## Discovery and reading
|
|
154
|
+
|
|
155
|
+
Call `search` with `{"query":"recovery","limit":5}`. Results contain
|
|
156
|
+
`{node, excerpt}`; pass a selected `node.reference` to `get` as
|
|
157
|
+
`{"reference":"<selected reference>"}`. Get also accepts exact item IDs/MIDs.
|
|
158
|
+
Use the project context selected above. One source excerpt is included per search
|
|
159
|
+
hit; it may omit content and does not replace a consecutive read. Item ID,
|
|
160
|
+
flavour, custom-field, and schema-relation filters select items only; path
|
|
161
|
+
filters also cover narrative. There is no node-kind filter.
|
|
162
|
+
|
|
163
|
+
Get returns `node`, `content`, `content_range`, `metadata`, and `metadata_range`.
|
|
164
|
+
Items return their parsed body and ordered metadata; other nodes return their
|
|
165
|
+
original Markdown span, including contained source for sections and documents,
|
|
166
|
+
with empty metadata. Read `node.context.parent` or `node.context.section` through
|
|
167
|
+
get when structural context is needed. Get does not enumerate neighbours or
|
|
168
|
+
accept `limit`.
|
|
169
|
+
|
|
170
|
+
Call `related` with `{"reference":"<selected reference>"}` for direct schema
|
|
171
|
+
relations, mentions, and containment. It returns `node` and
|
|
172
|
+
`connections`; pass a selected
|
|
173
|
+
`neighbour.reference` to `get` or another `related` call. Each call follows only
|
|
174
|
+
direct connections; there is no automatic expansion or hops option.
|
|
175
|
+
|
|
176
|
+
Use `direction:"incoming"`, `"outgoing"`, or `"symmetric"`; omission includes all.
|
|
177
|
+
Direction is canonical even when a relation filter uses an inverse alias. Related
|
|
178
|
+
`relations` accepts `schema:name` and `builtin:name`, with short names allowed
|
|
179
|
+
only when unambiguous in the vocabulary. Related `flavours` selects item
|
|
180
|
+
neighbours only. JSON represents containment as `contains` with direction;
|
|
181
|
+
human output displays its incoming view as `contained_by`. To find sibling
|
|
182
|
+
context, inspect `related` with `relations:["builtin:contains"]` and
|
|
183
|
+
`direction:"incoming"`, then select the parent's outgoing containment. Read
|
|
184
|
+
chosen children with `get`.
|
|
185
|
+
|
|
186
|
+
Search, item list, related, and get return `has_more` and `next_cursor`. Repeat
|
|
187
|
+
the same operation with that opaque `cursor`, keeping project, reference/query,
|
|
188
|
+
filters, and any supported limit unchanged. Continue until the needed content
|
|
189
|
+
is retrieved; full enumeration/read requires `has_more:false`. Get splits
|
|
190
|
+
consecutive content and metadata values across pages: use their byte/index
|
|
191
|
+
ranges to reconstruct complete values, including titles and repeated metadata.
|
|
192
|
+
Restart without a cursor after source/schema changes. Structural discovery
|
|
193
|
+
handles identify source in a document snapshot; if stale, search again.
|
|
194
|
+
Item MIDs retain durable identity. Search and related default to 20 entries
|
|
195
|
+
and accept `limit` from 1 through 100; related counts connections, including
|
|
196
|
+
different connections to the same neighbour. The byte budget may shorten pages.
|
|
77
197
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
198
|
+
Unified discovery responses use `format_version: 2`, independently of schema
|
|
199
|
+
format 3 and the application version. Inspect `node.kind` (item, section, block,
|
|
200
|
+
or document); only items have ID/MID/flavour. Item list retains its item-only
|
|
201
|
+
response. On upgrade, discard old cursors and update parsers for the mixed
|
|
202
|
+
`results`, consecutive `content`, and `connections` shapes above.
|
|
82
203
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
use their byte/index ranges to reconstruct content, including complete titles.
|
|
89
|
-
Restart without a cursor after source/schema changes. Related follows only direct
|
|
90
|
-
edges; choose further neighbours explicitly.
|
|
204
|
+
CLI retrieval uses the same JSON result fields:
|
|
205
|
+
`"${mara_cli[@]}" --project /absolute/project --format json search recovery --limit 5`,
|
|
206
|
+
then `"${mara_cli[@]}" --project /absolute/project --format json get '<reference>'`.
|
|
207
|
+
Use `related '<reference>'` for connections, `--relation builtin:mentions` to
|
|
208
|
+
select explicit mentions, and `--cursor '<next_cursor>'` for continuation.
|
|
91
209
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
210
|
+
## Inspect and change relationships
|
|
211
|
+
|
|
212
|
+
Schema lookup accepts inverse aliases and returns the canonical declaration,
|
|
213
|
+
`requested_name` and `inverse`. Lists show canonical names with aliases and
|
|
214
|
+
symmetry. Alias endpoint validation exchanges source and target first.
|
|
215
|
+
|
|
216
|
+
`related` returns each semantic schema edge once, with canonical `relation`,
|
|
217
|
+
endpoint-facing `label`, `direction`, `neighbour`, `edge` and `occurrence_count`.
|
|
218
|
+
Builtin connections retain `source`; use `relation_get` for schema locations.
|
|
219
|
+
Symmetric edges are excluded by incoming/outgoing filters. Directed self-edges
|
|
220
|
+
appear once as outgoing when direction is omitted. Different relation kinds
|
|
221
|
+
remain distinct. Item-list/search filters still select items with authored
|
|
222
|
+
metadata or inline assertions; canonical and alias filters select the same kind.
|
|
223
|
+
|
|
224
|
+
`relation_get {source,relation,target,limit?,cursor?}` returns the canonical
|
|
225
|
+
`edge`, total `occurrence_count` and a page of `occurrences`. Each occurrence
|
|
226
|
+
retains its author, spelling, source location and opaque `reference` selector.
|
|
227
|
+
Default limit is 20, maximum 100, with a 65,536-byte budget. Continue unchanged
|
|
228
|
+
until `has_more:false`; re-inspect after source/schema changes.
|
|
229
|
+
|
|
230
|
+
Add rejects an edge already asserted anywhere, including inverse, symmetric
|
|
231
|
+
and inline ID/MID equivalents. Direct source may intentionally repeat assertions.
|
|
232
|
+
`relation_remove {source,relation,target}` removes every occurrence across
|
|
233
|
+
included files. Supply `occurrence` from inspection to remove exactly one.
|
|
234
|
+
Stale or mismatched selectors fail without writes. Results report
|
|
235
|
+
`changed_occurrences`, `remaining_occurrences` and `edge_exists`. Inline removal
|
|
236
|
+
demotes internal `[[relation:target]]` to `[[target]]` and external assertions
|
|
237
|
+
to Markdown autolinks, preserving surrounding prose. The retained internal
|
|
238
|
+
mention still blocks deletion of its target.
|
|
239
|
+
|
|
240
|
+
Author `[[relation:ID]]`, `[[relation:MID]]`, or
|
|
241
|
+
`[[relation:external:https://host/path]]` in an item body using a canonical
|
|
242
|
+
schema name or inverse alias. External targets require `external: true` on the
|
|
243
|
+
relation declaration; Mara preserves their authored address and never fetches it.
|
|
244
|
+
No whitespace, labels or nested markup is allowed
|
|
245
|
+
inside the token. These assertions share metadata edge identity and produce no
|
|
246
|
+
builtin mention. Code, raw contexts and escaped openings remain literal; typed
|
|
247
|
+
tokens outside item bodies have no typed meaning. Unknown relations, malformed
|
|
248
|
+
tokens and invalid targets in supported contexts fail validation. Use body
|
|
249
|
+
creation/update to author inline assertions; relation add writes metadata.
|
|
250
|
+
|
|
251
|
+
For a format-1/2 or relation-vocabulary migration, follow
|
|
252
|
+
`docs/migration-0.3.mara.md` with the matching 0.3 executable. The supported
|
|
253
|
+
workflow is manual: save a Git checkpoint or project copy, review the complete
|
|
254
|
+
source diff, then require complete, valid schema and project validation. Mara
|
|
255
|
+
has no schema migration preview/apply command; `project_transaction_rollback`
|
|
256
|
+
does not undo manual edits. Preserve MIDs and unrelated declarations, fields,
|
|
257
|
+
prose and links. Existing relations remain directed with no alias unless the
|
|
258
|
+
schema explicitly changes. Review newly meaningful typed tokens, alias
|
|
259
|
+
collisions, all authored spellings and YAML rule paths before changing names.
|
|
260
|
+
When removing an inverse alias, inspect the canonical edge, reauthor it on its
|
|
261
|
+
canonical source if needed, remove inverse metadata, and demote inverse inline
|
|
262
|
+
tokens to bare mentions when preserving prose navigation. Never replace an
|
|
263
|
+
inverse name with the canonical name on the same item: that can reverse a
|
|
264
|
+
directed edge while validation still passes. Verify the canonical endpoints
|
|
265
|
+
after migration. Do not treat a direction, endpoint or meaning change as a
|
|
266
|
+
rename.
|
|
267
|
+
|
|
268
|
+
## Inspect trace coverage
|
|
269
|
+
|
|
270
|
+
Use `trace_matrix` (CLI `trace matrix`) for a read-only view of selected roots.
|
|
271
|
+
Select roots with `ids`, `flavours`, `fields`, `paths`, or `all:true`; pass either
|
|
272
|
+
enabled rule IRIs in `rules` or a request-local `check:{files,shape}`. CLI uses
|
|
273
|
+
repeatable `--id`, `--flavour`, `--field KEY=VALUE`, `--path`, and either
|
|
274
|
+
`--rule` or `--check-file` with `--shape`. Do not mix the two evaluation modes.
|
|
275
|
+
The check files supply shapes for this request only; they do not enable policy
|
|
276
|
+
for project validation. A named rule uses its own applicability and selection
|
|
277
|
+
within the requested roots.
|
|
278
|
+
|
|
279
|
+
Read each result state (`passed`, `failed`, `not_applicable`, `unavailable`),
|
|
280
|
+
the check and edge records, source locations, and per-evaluation `summaries`.
|
|
281
|
+
An external endpoint is terminal; an edge outside root selection can still
|
|
282
|
+
contribute to a check. Known rule failures are matrix data, while
|
|
283
|
+
`evaluation_complete:false` means the view could not be fully evaluated.
|
|
284
|
+
Continue with unchanged inputs and `next_cursor` until `has_more:false`;
|
|
285
|
+
restart after source, schema, or rule changes. CLI defaults to Markdown for
|
|
286
|
+
this command; `--format json` returns trace format 1. MCP returns JSON and
|
|
287
|
+
accepts `render:"markdown"` for the matching Markdown page. The output is a
|
|
288
|
+
projection, not a saved source of project knowledge.
|
|
289
|
+
|
|
290
|
+
## Preserve authored references
|
|
291
|
+
|
|
292
|
+
Use `[[ID]]`/`[[MID]]` in item bodies or narrative for item mentions, and
|
|
293
|
+
Markdown links for documents, heading sections, or explicit anchors, for example
|
|
294
|
+
`[policy](./policies.mara.md#retry-policy)`. Resolve relative paths from the
|
|
295
|
+
linking document. `mentions` and containment are derived; author them in
|
|
296
|
+
Markdown, not with relation mutations. Code examples and escaped references
|
|
297
|
+
remain literal. External URLs are not network-validated.
|
|
298
|
+
|
|
299
|
+
Rename rewrites typed relation targets and supported wiki mentions in items and
|
|
300
|
+
narrative, preserving MID. Create/update validate new internal references;
|
|
301
|
+
create/update/move/delete reject changes that break or retarget surviving links,
|
|
302
|
+
including generated anchors and links to nodes inside an item. Move can affect
|
|
303
|
+
relative links. Delete can be blocked by references to contained sections or
|
|
304
|
+
blocks. Resolve reported source locations before retrying; Markdown links are
|
|
305
|
+
not automatically repaired. Do not bypass a rejected mutation with raw edits.
|
|
95
306
|
|
|
96
307
|
## Keep metadata inputs distinct
|
|
97
308
|
|
|
@@ -107,7 +318,7 @@ The shared `:key: value` source syntax does not make these interchangeable:
|
|
|
107
318
|
- **Typed relations:** `justifies` and `satisfies` are relations, not custom
|
|
108
319
|
fields. `fields:[{"key":"justifies","value":"REQ-EXAMPLE"}]` is invalid.
|
|
109
320
|
Use creation `relations` or explicit relation operations; inspect allowed
|
|
110
|
-
source/target flavours first.
|
|
321
|
+
source/target flavours first. Use canonical names or declared inverse aliases; reverse navigation is derived.
|
|
111
322
|
|
|
112
323
|
CLI equivalents are `--title`, repeatable `--field KEY=VALUE`, update
|
|
113
324
|
`--clear-field KEY`, and creation `--relation NAME=TARGET`. Never pass a relation
|
|
@@ -115,8 +326,8 @@ through `--field`. CLI `--body -` reads stdin; MCP `body` is literal text.
|
|
|
115
326
|
|
|
116
327
|
## Author and verify
|
|
117
328
|
|
|
118
|
-
1. Inspect the schema and resolve existing targets with `
|
|
119
|
-
example, the schema permits `decision` → `justifies` → `requirement`, and
|
|
329
|
+
1. Inspect the schema and resolve existing targets with `get` using `reference`.
|
|
330
|
+
In this example, the schema permits `decision` → `justifies` → `requirement`, and
|
|
120
331
|
`REQ-EXAMPLE` already exists. Replace `/absolute/project` with the selected root,
|
|
121
332
|
or omit `project` when the server is bound to it.
|
|
122
333
|
2. Call `item_create` with a meaningful body and any required custom fields:
|
|
@@ -152,10 +363,10 @@ atomically, rejecting the whole request if an edge is invalid. Targets accept
|
|
|
152
363
|
exact human IDs or MIDs. Do not add the same edge again; use `relation_add` and
|
|
153
364
|
`relation_remove` for later changes (both take `source`, `relation`, `target`).
|
|
154
365
|
|
|
155
|
-
5. Call `
|
|
156
|
-
|
|
157
|
-
`
|
|
158
|
-
`
|
|
366
|
+
5. Call `get` with `reference:"ADR-EXAMPLE"`; inspect `node` for the generated
|
|
367
|
+
MID/title, `content` for the body, and `metadata` for authored values.
|
|
368
|
+
Call `related` with `reference:"ADR-EXAMPLE",direction:"outgoing"`, then with
|
|
369
|
+
`reference:"REQ-EXAMPLE",direction:"incoming"` to verify both views of the edge.
|
|
159
370
|
6. Call `item_validate` with `id:"ADR-EXAMPLE"`; use `project_validate` for
|
|
160
371
|
corpus-wide integrity after relation or reference changes. Use the same project
|
|
161
372
|
context. Require `valid:true`, not just successful transport. Project
|
|
@@ -167,24 +378,18 @@ validation. Pending transactions block mutations; use `project_transaction_rollb
|
|
|
167
378
|
other writers.
|
|
168
379
|
|
|
169
380
|
For the same authoring workflow through CLI, after resolving `mara_cli` and
|
|
170
|
-
`REQ-EXAMPLE`, use initial relations atomically
|
|
171
|
-
`--relation`, and inspect both directions:
|
|
381
|
+
`REQ-EXAMPLE`, use initial relations atomically and inspect both directions:
|
|
172
382
|
|
|
173
383
|
```bash
|
|
174
384
|
mara_project=/absolute/project
|
|
175
385
|
"${mara_cli[@]}" --project "$mara_project" --format json schema get
|
|
176
|
-
"${mara_cli[@]}" --project "$mara_project" --format json
|
|
386
|
+
"${mara_cli[@]}" --project "$mara_project" --format json get REQ-EXAMPLE
|
|
177
387
|
"${mara_cli[@]}" --project "$mara_project" --format json item create decision ADR-EXAMPLE decisions.mara.md \
|
|
178
388
|
--title 'Keep edits recoverable' \
|
|
179
389
|
--body 'Preserve the previous content until validation succeeds so rejected edits can be retried.' \
|
|
180
390
|
--relation justifies=REQ-EXAMPLE
|
|
181
|
-
"${mara_cli[@]}" --project "$mara_project" --format json
|
|
182
|
-
"${mara_cli[@]}" --project "$mara_project" --format json
|
|
183
|
-
"${mara_cli[@]}" --project "$mara_project" --format json
|
|
391
|
+
"${mara_cli[@]}" --project "$mara_project" --format json get ADR-EXAMPLE
|
|
392
|
+
"${mara_cli[@]}" --project "$mara_project" --format json related ADR-EXAMPLE --direction outgoing
|
|
393
|
+
"${mara_cli[@]}" --project "$mara_project" --format json related REQ-EXAMPLE --direction incoming
|
|
184
394
|
"${mara_cli[@]}" --project "$mara_project" --format json project validate
|
|
185
395
|
```
|
|
186
|
-
|
|
187
|
-
If the selected version lacks initial relations, or to use separate create/add,
|
|
188
|
-
omit `--relation` during creation and then run
|
|
189
|
-
`relation add ADR-EXAMPLE justifies REQ-EXAMPLE` with the same launcher and global
|
|
190
|
-
project/JSON options. Check creation completeness and validation results as above.
|