@convesoft/mara 0.2.0-alpha.0 → 0.2.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 +108 -80
- package/package.json +5 -5
- package/plugin.json +1 -1
- package/skills/mara/SKILL.md +130 -39
package/README.md
CHANGED
|
@@ -2,28 +2,43 @@
|
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
8
|
+
Mara 0.2.0 provides schema format 2 with flavour
|
|
9
|
+
selection guidance, an engineering template, and unified `search`, `get`, and
|
|
10
|
+
`related`. Start with the [0.2 migration guide](docs/migration-0.2.mara.md) for
|
|
11
|
+
an existing project. The [0.1.0 documentation](https://github.com/convesoft/mara/tree/v0.1.0)
|
|
12
|
+
describes the older released interface; use documentation and skill from the
|
|
13
|
+
same revision as your executable.
|
|
14
|
+
|
|
15
|
+
## Run Mara
|
|
16
|
+
|
|
17
|
+
Build the implementation described here with the pinned Rust toolchain:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
cargo build --locked --release
|
|
21
|
+
./target/release/mara --help
|
|
22
|
+
```
|
|
14
23
|
|
|
15
|
-
|
|
24
|
+
The examples below use `mara` to mean this executable or an installed version
|
|
25
|
+
that exposes the same interface. Register its absolute path for MCP. The
|
|
26
|
+
checkout's version string alone does not establish which unreleased changes
|
|
27
|
+
an older published prerelease includes; check its help and matching release
|
|
28
|
+
notes before using the 0.2 workflow.
|
|
16
29
|
|
|
17
|
-
|
|
30
|
+
Published npm packages contain prebuilt native binaries and use no install
|
|
31
|
+
scripts or Rust toolchain. Run the stable 0.2.0 version:
|
|
18
32
|
|
|
19
33
|
```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
|
|
34
|
+
npx -y '@convesoft/mara@0.2.0' --version
|
|
35
|
+
npx -y '@convesoft/mara@0.2.0' --help
|
|
23
36
|
```
|
|
24
37
|
|
|
25
|
-
|
|
26
|
-
|
|
38
|
+
Keep that exact pin in CLI and MCP launchers. Supported hosts are x64 and
|
|
39
|
+
arm64 macOS, plus x64 and arm64 Linux compatible with Ubuntu 22.04's glibc
|
|
40
|
+
baseline. Distribution guarantees are in
|
|
41
|
+
[distribution and release](docs/distribution.mara.md).
|
|
27
42
|
|
|
28
43
|
## Configure an MCP client
|
|
29
44
|
|
|
@@ -31,51 +46,41 @@ For a client that starts stdio servers in the project directory:
|
|
|
31
46
|
|
|
32
47
|
```toml
|
|
33
48
|
[mcp_servers.mara]
|
|
34
|
-
command = "
|
|
35
|
-
args = ["
|
|
49
|
+
command = "/absolute/path/to/mara"
|
|
50
|
+
args = ["mcp"]
|
|
36
51
|
```
|
|
37
52
|
|
|
38
|
-
To bind the server to one project regardless of its execution directory
|
|
39
|
-
`--project` after `mcp`:
|
|
53
|
+
To bind the server to one project regardless of its execution directory:
|
|
40
54
|
|
|
41
55
|
```toml
|
|
42
56
|
[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
|
-
]
|
|
57
|
+
command = "/absolute/path/to/mara"
|
|
58
|
+
args = ["mcp", "--project", "/absolute/path/to/project"]
|
|
51
59
|
```
|
|
52
60
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
61
|
+
For npm, use `command = "npx"` and prepend `"-y"` and
|
|
62
|
+
`"@convesoft/mara@<version>"` to the arguments after substituting the exact pin.
|
|
63
|
+
Without `--project`, project-bound tools accept an absolute `project` path or
|
|
64
|
+
discover the nearest `.mara/project.toml` from the server's execution directory.
|
|
65
|
+
A bound server rejects request-level project overrides; omit that parameter.
|
|
56
66
|
|
|
57
67
|
## Configure Codex
|
|
58
68
|
|
|
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:
|
|
69
|
+
Register the executable and install [the Mara skill](skills/mara/SKILL.md)
|
|
70
|
+
separately from the same checkout or release:
|
|
68
71
|
|
|
69
72
|
```bash
|
|
70
73
|
codex mcp add mara -- /absolute/path/to/mara mcp
|
|
71
74
|
```
|
|
72
75
|
|
|
73
|
-
|
|
74
|
-
|
|
76
|
+
Install the `skills/mara` directory through your client's skill installation
|
|
77
|
+
workflow. Installing the skill does not install an executable; it reuses the
|
|
78
|
+
configured MCP launcher for CLI fallback. For a published version, the npm
|
|
79
|
+
package contains the matching skill as well as optional portable Agent Plugins
|
|
80
|
+
1.0 metadata and MCP configuration.
|
|
75
81
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
package through the Convesoft marketplace as a convenience:
|
|
82
|
+
Compatible clients may install the complete package through the Convesoft
|
|
83
|
+
marketplace as a convenience:
|
|
79
84
|
|
|
80
85
|
```bash
|
|
81
86
|
codex plugin marketplace add convesoft/mara
|
|
@@ -86,54 +91,77 @@ The complete plugin is not a release compatibility target. Do not install it
|
|
|
86
91
|
alongside an equivalent manually configured Mara MCP server. Neither onboarding
|
|
87
92
|
route modifies project `AGENTS.md`.
|
|
88
93
|
|
|
89
|
-
##
|
|
94
|
+
## Start authoring
|
|
95
|
+
|
|
96
|
+
Run this in a new project directory; `knowledge.mara.md` is created by the
|
|
97
|
+
first item operation:
|
|
90
98
|
|
|
91
99
|
```bash
|
|
92
|
-
mara project init
|
|
93
|
-
mara schema
|
|
94
|
-
mara
|
|
95
|
-
|
|
96
|
-
|
|
100
|
+
mara project init --template engineering
|
|
101
|
+
mara schema list flavour
|
|
102
|
+
mara schema get flavour requirement
|
|
103
|
+
mara schema get relation verifies
|
|
104
|
+
mara item create requirement REQ-ACCESS knowledge.mara.md \
|
|
105
|
+
--title "Permit access" --body "An authorized user can access the service."
|
|
106
|
+
mara item create verification VER-ACCESS knowledge.mara.md \
|
|
107
|
+
--title "Check access" \
|
|
108
|
+
--body "Demonstrate that an authorized user can access the service." \
|
|
109
|
+
--relation verifies=REQ-ACCESS
|
|
97
110
|
mara project validate
|
|
98
|
-
mara item search "primary workflow"
|
|
99
|
-
mara item get REQ-EXAMPLE
|
|
100
111
|
```
|
|
101
112
|
|
|
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.
|
|
113
|
+
`minimal` remains the default template; `empty` declares no vocabulary.
|
|
114
|
+
`engineering` supplies engineering flavours and traceability relations.
|
|
115
|
+
Templates create configuration and an editable schema only. Before creating an
|
|
116
|
+
item, use the flavour's `description`, `use_when`, `avoid_when`, and
|
|
117
|
+
`distinguish_from` to choose appropriate knowledge, then inspect its ID prefix,
|
|
118
|
+
body, and field constraints. These guidance keys belong to the schema, not
|
|
119
|
+
item metadata. See [guided authoring](docs/guided-authoring.mara.md) for the
|
|
120
|
+
schema contract and engineering relation meanings.
|
|
124
121
|
|
|
125
|
-
##
|
|
122
|
+
## Discovery and reading
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
mara --format json search "authorized user"
|
|
126
|
+
mara --format json get REQ-ACCESS
|
|
127
|
+
mara --format json related REQ-ACCESS --direction incoming --relation verifies
|
|
128
|
+
mara --format json get VER-ACCESS
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
CLI and MCP use `search`, `get`, and `related`; MCP get/related take
|
|
132
|
+
`{"reference":"REQ-ACCESS"}`. Search returns mixed item, section, and Markdown
|
|
133
|
+
block hits with one excerpt each. Pass a hit's `node.reference` to get or
|
|
134
|
+
related, then read selected `connections[].neighbour.reference` values.
|
|
135
|
+
`node.context.parent` identifies direct structural context. Documents and
|
|
136
|
+
sections can be read and navigated without client filesystem access.
|
|
137
|
+
|
|
138
|
+
Repeat a paginated call with its `next_cursor` until `has_more:false`, keeping
|
|
139
|
+
all other inputs unchanged. Get returns consecutive content and ordered item
|
|
140
|
+
metadata fragments; search excerpts are only for selection. Search and related
|
|
141
|
+
accept `limit`; get does not. Item filters exclude narrative; project-relative
|
|
142
|
+
path filters cover all search result kinds. For response fields, relation
|
|
143
|
+
namespaces, containment, and handle lifetime, see
|
|
144
|
+
[the discovery contract](docs/discovery.mara.md).
|
|
145
|
+
|
|
146
|
+
Item authoring, list, and validation remain under `item`; relation mutations
|
|
147
|
+
write schema-defined item edges. Mentions and containment derive from Markdown.
|
|
148
|
+
Editing rejects changes that break or retarget surviving internal links; resolve
|
|
149
|
+
reported impacts before retrying. See [item editing](docs/editing.mara.md) and
|
|
150
|
+
[Markdown links and mutation safety](docs/discovery.mara.md#item-mutation-and-link-safety).
|
|
151
|
+
Use `mara --help` or `mara <command> --help` for command and argument guidance.
|
|
126
152
|
|
|
127
|
-
|
|
153
|
+
## Development
|
|
128
154
|
|
|
129
155
|
```bash
|
|
130
|
-
cargo
|
|
156
|
+
cargo fmt --all -- --check
|
|
131
157
|
cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
132
|
-
cargo
|
|
158
|
+
cargo test --locked --all-targets
|
|
159
|
+
cargo run --locked --quiet -- --format json project validate
|
|
160
|
+
scripts/smoke-npm.sh target/release/mara
|
|
133
161
|
```
|
|
134
162
|
|
|
135
|
-
See [
|
|
136
|
-
[
|
|
163
|
+
See [the documentation index](docs/index.mara.md), [ROADMAP.md](ROADMAP.md),
|
|
164
|
+
[AGENTS.md](AGENTS.md), and [SECURITY.md](SECURITY.md).
|
|
137
165
|
|
|
138
166
|
## License
|
|
139
167
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@convesoft/mara",
|
|
3
|
-
"version": "0.2.0
|
|
3
|
+
"version": "0.2.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.2.0
|
|
22
|
-
"@convesoft/mara-linux-arm64-gnu": "0.2.0
|
|
23
|
-
"@convesoft/mara-darwin-x64": "0.2.0
|
|
24
|
-
"@convesoft/mara-darwin-arm64": "0.2.0
|
|
21
|
+
"@convesoft/mara-linux-x64-gnu": "0.2.0",
|
|
22
|
+
"@convesoft/mara-linux-arm64-gnu": "0.2.0",
|
|
23
|
+
"@convesoft/mara-darwin-x64": "0.2.0",
|
|
24
|
+
"@convesoft/mara-darwin-arm64": "0.2.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,12 @@ 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 0.2 interface: schema format 2 and unified `search`,
|
|
14
|
+
`get`, and `related`. Use the skill shipped with the selected executable or
|
|
15
|
+
the same source revision. If an older installation exposes a different
|
|
16
|
+
interface, report the mismatch and use its matching guidance; do not silently
|
|
17
|
+
change the version pin or substitute removed commands.
|
|
18
|
+
|
|
13
19
|
## Resolve the CLI fallback
|
|
14
20
|
|
|
15
21
|
Installing the skill does not install `mara` on PATH. Reuse the configured MCP
|
|
@@ -48,17 +54,55 @@ is `"${mara_cli[@]}" --project /absolute/project --format json project init --te
|
|
|
48
54
|
where `<template>` is the selected `minimal`, `empty`, or `engineering` name.
|
|
49
55
|
Do not create or modify `AGENTS.md` as part of Mara onboarding.
|
|
50
56
|
|
|
57
|
+
## Choose vocabulary from the schema
|
|
58
|
+
|
|
59
|
+
Call `schema_list` with `{"kind":"flavour"}`, then `schema_get` with
|
|
60
|
+
`{"kind":"flavour","name":"requirement"}` for a candidate. CLI equivalents
|
|
61
|
+
are `schema list flavour` and `schema get flavour requirement`.
|
|
62
|
+
|
|
63
|
+
- `description` states purpose; `use_when` identifies suitable knowledge.
|
|
64
|
+
- `avoid_when` excludes unsuitable content; `distinguish_from` compares
|
|
65
|
+
confusable flavours. Read the alternative declaration when the distinction
|
|
66
|
+
affects your choice.
|
|
67
|
+
- `id_prefix`, `body`, and `fields` specify creation constraints. Guidance keys
|
|
68
|
+
belong to the schema declaration, not an item's `fields` or body.
|
|
69
|
+
|
|
70
|
+
Use the selected project's declarations, including custom flavours. Keep
|
|
71
|
+
supporting narrative as Markdown when it does not need an independent identity;
|
|
72
|
+
search/get/related can still discover, read, and navigate it.
|
|
73
|
+
|
|
74
|
+
Schema format 2 requires all four guidance keys directly on every flavour:
|
|
75
|
+
a nonblank `description`, a nonempty list of nonblank `use_when` entries,
|
|
76
|
+
an `avoid_when` list (`[]` is valid), and a `distinguish_from` mapping (`{}` is
|
|
77
|
+
valid). Distinction targets must be other declared flavours with nonblank
|
|
78
|
+
explanations. When asked to migrate format 1, edit the existing schema in place,
|
|
79
|
+
set `format_version: 2`, and supply meaningful guidance. Preserve custom
|
|
80
|
+
flavours, prefixes, fields, relations, document bytes, IDs, and MIDs; do not
|
|
81
|
+
reinitialize or replace the schema with a template. Require `valid:true` from
|
|
82
|
+
both `schema_validate` and `project_validate` (CLI `schema validate` and
|
|
83
|
+
`project validate`).
|
|
84
|
+
|
|
85
|
+
For the engineering template, inspect `schema_get` relation declarations before
|
|
86
|
+
connecting items. `verification` describes a repeatable check; `evidence`
|
|
87
|
+
records its result. The added relations are `verifies` (verification →
|
|
88
|
+
requirement/design), `validates` (verification → goal/scenario), `evidences`
|
|
89
|
+
(evidence → verification), `implements` (artifact → requirement/design),
|
|
90
|
+
`affects` (risk → affected knowledge), and `mitigates`
|
|
91
|
+
(requirement/design/decision/verification → risk). Add only meaningful links;
|
|
92
|
+
no complete trace chain or placeholder items are required. Existing projects
|
|
93
|
+
do not gain these declarations automatically.
|
|
94
|
+
|
|
51
95
|
## Choose the operation
|
|
52
96
|
|
|
53
97
|
CLI entries below follow `"${mara_cli[@]}" --project /absolute/project --format json`;
|
|
54
|
-
inspect `<
|
|
98
|
+
inspect `<command> --help` for positional arguments and options.
|
|
55
99
|
|
|
56
100
|
| Intent | MCP operation | CLI command |
|
|
57
101
|
|---|---|---|
|
|
58
|
-
| Discover vocabulary and field/edge constraints | `schema_list
|
|
59
|
-
|
|
|
60
|
-
| Read
|
|
61
|
-
| Inspect direct
|
|
102
|
+
| 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` |
|
|
103
|
+
| Search items and narrative, or list items with exact filters | `search` or `item_list` | `search`, `item list` |
|
|
104
|
+
| Read an item, section, Markdown block, or document | `get` | `get` |
|
|
105
|
+
| Inspect direct connections from any node, then read a selected neighbour | `related`, then `get` | `related`, then `get` |
|
|
62
106
|
| Create an item, optionally with initial edges | `item_create` | `item create` |
|
|
63
107
|
| Change title, custom fields, or body | `item_update` | `item update` |
|
|
64
108
|
| Relocate an item; preserve ID and MID | `item_move` | `item move` |
|
|
@@ -73,25 +117,78 @@ for correcting the input or selecting the right operation; it is not a reason
|
|
|
73
117
|
to bypass validation by editing source lines. Mara source files remain canonical;
|
|
74
118
|
MCP results are not a separate authoring store.
|
|
75
119
|
|
|
76
|
-
##
|
|
120
|
+
## Discovery and reading
|
|
121
|
+
|
|
122
|
+
Call `search` with `{"query":"recovery","limit":5}`. Results contain
|
|
123
|
+
`{node, excerpt}`; pass a selected `node.reference` to `get` as
|
|
124
|
+
`{"reference":"<selected reference>"}`. Get also accepts exact item IDs/MIDs.
|
|
125
|
+
Use the project context selected above. One source excerpt is included per search
|
|
126
|
+
hit; it may omit content and does not replace a consecutive read. Item ID,
|
|
127
|
+
flavour, custom-field, and schema-relation filters select items only; path
|
|
128
|
+
filters also cover narrative. There is no node-kind filter.
|
|
77
129
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
130
|
+
Get returns `node`, `content`, `content_range`, `metadata`, and `metadata_range`.
|
|
131
|
+
Items return their parsed body and ordered metadata; other nodes return their
|
|
132
|
+
original Markdown span, including contained source for sections and documents,
|
|
133
|
+
with empty metadata. Read `node.context.parent` or `node.context.section` through
|
|
134
|
+
get when structural context is needed. Get does not enumerate neighbours or
|
|
135
|
+
accept `limit`.
|
|
82
136
|
|
|
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.
|
|
137
|
+
Call `related` with `{"reference":"<selected reference>"}` for direct schema
|
|
138
|
+
relations, mentions, and containment. It returns `node` and
|
|
139
|
+
`connections:[{relation,direction,neighbour,source}]`; pass a selected
|
|
140
|
+
`neighbour.reference` to `get` or another `related` call. Each call follows only
|
|
141
|
+
direct connections; there is no automatic expansion or hops option.
|
|
91
142
|
|
|
92
|
-
|
|
93
|
-
`
|
|
94
|
-
|
|
143
|
+
Use `direction:"incoming"` or `"outgoing"`; omission includes both. Related
|
|
144
|
+
`relations` accepts `schema:name` and `builtin:name`, with short names allowed
|
|
145
|
+
only when unambiguous in the vocabulary. Related `flavours` selects item
|
|
146
|
+
neighbours only. JSON represents containment as `contains` with direction;
|
|
147
|
+
human output displays its incoming view as `contained_by`. To find sibling
|
|
148
|
+
context, inspect `related` with `relations:["builtin:contains"]` and
|
|
149
|
+
`direction:"incoming"`, then select the parent's outgoing containment. Read
|
|
150
|
+
chosen children with `get`.
|
|
151
|
+
|
|
152
|
+
Search, item list, related, and get return `has_more` and `next_cursor`. Repeat
|
|
153
|
+
the same operation with that opaque `cursor`, keeping project, reference/query,
|
|
154
|
+
filters, and any supported limit unchanged. Continue until the needed content
|
|
155
|
+
is retrieved; full enumeration/read requires `has_more:false`. Get splits
|
|
156
|
+
consecutive content and metadata values across pages: use their byte/index
|
|
157
|
+
ranges to reconstruct complete values, including titles and repeated metadata.
|
|
158
|
+
Restart without a cursor after source/schema changes. Structural discovery
|
|
159
|
+
handles identify source in a document snapshot; if stale, search again.
|
|
160
|
+
Item MIDs retain durable identity. Search and related default to 20 entries
|
|
161
|
+
and accept `limit` from 1 through 100; related counts connections, including
|
|
162
|
+
different connections to the same neighbour. The byte budget may shorten pages.
|
|
163
|
+
|
|
164
|
+
Unified discovery responses use `format_version: 1`, independently of schema
|
|
165
|
+
format 2 and the application version. Inspect `node.kind` (item, section, block,
|
|
166
|
+
or document); only items have ID/MID/flavour. Item list retains its item-only
|
|
167
|
+
response. On upgrade, discard old cursors and update parsers for the mixed
|
|
168
|
+
`results`, consecutive `content`, and `connections` shapes above.
|
|
169
|
+
|
|
170
|
+
CLI retrieval uses the same JSON result fields:
|
|
171
|
+
`"${mara_cli[@]}" --project /absolute/project --format json search recovery --limit 5`,
|
|
172
|
+
then `"${mara_cli[@]}" --project /absolute/project --format json get '<reference>'`.
|
|
173
|
+
Use `related '<reference>'` for connections, `--relation builtin:mentions` to
|
|
174
|
+
select explicit mentions, and `--cursor '<next_cursor>'` for continuation.
|
|
175
|
+
|
|
176
|
+
## Preserve authored references
|
|
177
|
+
|
|
178
|
+
Use `[[ID]]`/`[[MID]]` in item bodies or narrative for item mentions, and
|
|
179
|
+
Markdown links for documents, heading sections, or explicit anchors, for example
|
|
180
|
+
`[policy](./policies.mara.md#retry-policy)`. Resolve relative paths from the
|
|
181
|
+
linking document. `mentions` and containment are derived; author them in
|
|
182
|
+
Markdown, not with relation mutations. Code examples and escaped references
|
|
183
|
+
remain literal. External URLs are not network-validated.
|
|
184
|
+
|
|
185
|
+
Rename rewrites typed relation targets and supported wiki mentions in items and
|
|
186
|
+
narrative, preserving MID. Create/update validate new internal references;
|
|
187
|
+
create/update/move/delete reject changes that break or retarget surviving links,
|
|
188
|
+
including generated anchors and links to nodes inside an item. Move can affect
|
|
189
|
+
relative links. Delete can be blocked by references to contained sections or
|
|
190
|
+
blocks. Resolve reported source locations before retrying; Markdown links are
|
|
191
|
+
not automatically repaired. Do not bypass a rejected mutation with raw edits.
|
|
95
192
|
|
|
96
193
|
## Keep metadata inputs distinct
|
|
97
194
|
|
|
@@ -115,8 +212,8 @@ through `--field`. CLI `--body -` reads stdin; MCP `body` is literal text.
|
|
|
115
212
|
|
|
116
213
|
## Author and verify
|
|
117
214
|
|
|
118
|
-
1. Inspect the schema and resolve existing targets with `
|
|
119
|
-
example, the schema permits `decision` → `justifies` → `requirement`, and
|
|
215
|
+
1. Inspect the schema and resolve existing targets with `get` using `reference`.
|
|
216
|
+
In this example, the schema permits `decision` → `justifies` → `requirement`, and
|
|
120
217
|
`REQ-EXAMPLE` already exists. Replace `/absolute/project` with the selected root,
|
|
121
218
|
or omit `project` when the server is bound to it.
|
|
122
219
|
2. Call `item_create` with a meaningful body and any required custom fields:
|
|
@@ -152,10 +249,10 @@ atomically, rejecting the whole request if an edge is invalid. Targets accept
|
|
|
152
249
|
exact human IDs or MIDs. Do not add the same edge again; use `relation_add` and
|
|
153
250
|
`relation_remove` for later changes (both take `source`, `relation`, `target`).
|
|
154
251
|
|
|
155
|
-
5. Call `
|
|
156
|
-
|
|
157
|
-
`
|
|
158
|
-
`
|
|
252
|
+
5. Call `get` with `reference:"ADR-EXAMPLE"`; inspect `node` for the generated
|
|
253
|
+
MID/title, `content` for the body, and `metadata` for authored values.
|
|
254
|
+
Call `related` with `reference:"ADR-EXAMPLE",direction:"outgoing"`, then with
|
|
255
|
+
`reference:"REQ-EXAMPLE",direction:"incoming"` to verify both views of the edge.
|
|
159
256
|
6. Call `item_validate` with `id:"ADR-EXAMPLE"`; use `project_validate` for
|
|
160
257
|
corpus-wide integrity after relation or reference changes. Use the same project
|
|
161
258
|
context. Require `valid:true`, not just successful transport. Project
|
|
@@ -167,24 +264,18 @@ validation. Pending transactions block mutations; use `project_transaction_rollb
|
|
|
167
264
|
other writers.
|
|
168
265
|
|
|
169
266
|
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:
|
|
267
|
+
`REQ-EXAMPLE`, use initial relations atomically and inspect both directions:
|
|
172
268
|
|
|
173
269
|
```bash
|
|
174
270
|
mara_project=/absolute/project
|
|
175
271
|
"${mara_cli[@]}" --project "$mara_project" --format json schema get
|
|
176
|
-
"${mara_cli[@]}" --project "$mara_project" --format json
|
|
272
|
+
"${mara_cli[@]}" --project "$mara_project" --format json get REQ-EXAMPLE
|
|
177
273
|
"${mara_cli[@]}" --project "$mara_project" --format json item create decision ADR-EXAMPLE decisions.mara.md \
|
|
178
274
|
--title 'Keep edits recoverable' \
|
|
179
275
|
--body 'Preserve the previous content until validation succeeds so rejected edits can be retried.' \
|
|
180
276
|
--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
|
|
277
|
+
"${mara_cli[@]}" --project "$mara_project" --format json get ADR-EXAMPLE
|
|
278
|
+
"${mara_cli[@]}" --project "$mara_project" --format json related ADR-EXAMPLE --direction outgoing
|
|
279
|
+
"${mara_cli[@]}" --project "$mara_project" --format json related REQ-EXAMPLE --direction incoming
|
|
184
280
|
"${mara_cli[@]}" --project "$mara_project" --format json project validate
|
|
185
281
|
```
|
|
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.
|