[devin-ai-integration]

What and why

Markdown and AsciiDoc document bodies can now read model values into the prose, completing the macro set issue #1309 asked for (references landed with #1453; AsciiDoc bodies landed with #1454):

• Markdown: [label](sysml:value:<target>) — [](sysml:value:telescope.mass) renders 2290000 [kg], [Mass:](sysml:value:telescope.mass) renders Mass: 2290000 [kg].
• AsciiDoc: sysml:value[<target>] and sysml:value[<target>, label] (the macro's second positional attribute is the label, as sysml:ref[…] already does); the converter previously recognised and refused the macro.

Both markups yield one markup.RunValue, planned by docplan as a RunValue run and evaluated by docir into an ordinary plain run, so no backend changes were needed.

Design decisions:

• Target resolution goes through the same resolveTargetValue as Ref::target / [label](sysml:<target>): a qualified name or feature chain in the body's scope. A feature chain reads from its root (telescope.mount.mass reads mount.mass below telescope; a member written mount::mass or a 'quoted name' is one path segment each), a bare or qualified name from the feature's owner (Telescope::aperture reads the nominal value).
• Element-valued targets are an error. A part, port, content block, definition, a ref to one of those, or anything else that is not a data-valued feature (an attribute, calculation or enumeration usage, or a ref whose types, derived as KerML derives Feature::type from the features it subsets, redefines or references, are data types only) is refused when planning with invalid-value-target naming the element and its kind (Observatory::Telescope::mount, a part usage); sysml: without value: is the way to name an element. Unresolvable targets are unknown-value-target.
• Evaluation reuses the cell path. New queryexec.ReadFeature builds the same executor a query uses and reads the property through propertyValues, so a value renders exactly as the same feature does in a SpanColumn cell (valuesText, shared with cellText): quantities with their unit, strings, booleans, enumeration literals, multi-valued features joined with , . Over a session whose roots include the chain's root (-run, a document rendered while the REPL holds objects), the object's current value is read as Objects rows read it; ReadFeature walks a member path through nested objects, which the column path does not do today for object rows.
• No value → typed error, no blank. A feature with no value fails evaluation with empty-value naming the content block and the feature. No default syntax was added: cells have none either.
• Labels: empty label renders the value alone; a label is followed by one space and the value. Every run keeps its Origin inside the body.

Known limit, stated in the manual's terms: a feature whose name coincides with a queryable property (name, qualifiedName, …) reads as the column of that name does.

Merge order: #1454 (merged) → this PR, now against develop with current origin/develop merged in.

Overlap with #1477 (headings open sections, also against develop): both touch internal/ir/docplan/markup/{markup,markdown,asciidoc}.go, markup_bodies.go, plan.go, errors.go, scripts/asciidoc/asciidoctor-json.js, docs/manual/authoring.md and the generated docs/reference/diagnostics.md. This change is additive (new RunValue, one case each in markdown.go, asciidoc.go and markup_bodies.go; the new logic lives in docplan/value_runs.go and queryexec/feature.go). A dry merge of the two heads conflicts in asciidoc.go, asciidoctor-json.js, authoring.md and diagnostics.md, each an adjacent addition; whichever lands second re-merges and regenerates the catalogue with make diagnostics-catalogue. Both add a manual example, and docs/manual/examples is an input of the API JSON differential: the baseline here is re-recorded over develop plus values.sysml (one more file; +96 matched and +12 pilot-only elements, no movement in ours-only or type mismatches), so the second to land re-records it again with go run -C tools ./cmd/pilot-apijson-diff -update and make docs-counts.

Proposed wording for the vendored DocumentQueries.sysml (not edited here), in Paragraph's doc comment: "A Markdown or AsciiDoc body may read a feature's value into the prose (sysml:value:, sysml:value[…]); the value renders as a SpanColumn cell of that feature would."

How it was verified

• internal/ir/docplan/markup: Markdown labelled and bare sysml:value: destinations; AsciiDoc sysml:value[a.mass] / sysml:value[a.b, Mass:] against the converter's JSON, refusals for a value in a table cell and a macro without target.
• internal/ir/docplan: value_runs_test.go — chain, nested chain and qualified-name targets with root, member path, label and origin; errors for unknown, unparseable, part-usage, definition and content-block targets; AsciiDoc through the recorded converter fixture testdata/asciidoc_values.{adoc,json}.
• internal/doc/docir: values_test.go — real, string, boolean, enumeration, quantity with unit and multi-valued attributes in a paragraph and a list item; empty-value; session-bound read of a written object value.
• internal/doc/docrender: values_report.sysml with Markdown and HTML goldens.
• Manual: docs/manual/authoring.md (both prose sections), worked example docs/manual/examples/values.{sysml,md} rendered end to end by TestManualValuesExampleMatchesCommittedOutput.
• Gate: go build ./..., go vet ./..., gofmt -l . empty, make lint, go test -race over internal/ir/docplan/... internal/doc/... internal/check/... internal/frontend/grpc/... cmd/sysml/..., make wasm-check (sysml-core 6,613,880 gz under the 6,800,000 budget), make docs-check, make diagnostics-check (catalogue regenerated), python3 scripts/changelog.py check, make docs (strict site build), go run -C tools ./cmd/pilot-apijson-diff -update with the pinned exporter (TestCommittedBaselineStatesThisRepositorysProvenance, TestRecordStatesTheBaselinesFigures and make docs-counts green), go test ./tests/... and the training, pilot and spec-example corpus gates with their require variables set.

Checklist

• make test and make lint pass locally (race suite run over the touched trees and ./tests/...)
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (compliance rows need nothing: the census is counted at docs build)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/13dea4832ad84ed59b3a7ccea88fdfa3
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/13dea4832ad84ed59b3a7ccea88fdfa3?variant=devin
Requested by: @HuiJun

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring