docs(skills): describe Comark authoring recovery and repairs (#1754)

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

skills/memory-comark/SKILL.md

@@ -68,8 +68,9 @@ Rules that matter:
   `bm-kanban`; people can tick boxes from the rendered note.
 - **Never put HTML, scripts, styles, or classes in a note**, and never wrap a
   component in a code fence (a fenced block stays literal code).
-- **Use only registered props.** An unknown attribute makes the directive
-  unparseable, and it shows as raw text.
+- **Use only registered props.** An unknown attribute produces `prop-unknown`
+  in a warning frame with the original source and registered props; it is never
+  silently dropped.
 
 A checklist and a board:
 
@@ -158,8 +159,11 @@ as a snapshot in prose and keep them in the chart's row grammar.
 - The rich editor normalizes formatting when a person edits the note: attribute
   order changes and YAML blocks come back as JSON. Values survive; do not fight
   the formatting.
-- Keep the closing `::` lines. An unclosed component swallows the rest of the
-  note into its body.
+- Keep the closing `::` lines. A block with a body but no close produces
+  `directive-unclosed`; the opener and YAML props appear in a warning while
+  following Markdown stays visible. Add the close at the intended boundary in
+  source; the editor never guesses it. Standalone leaves with no body remain
+  valid, though new components should use explicit closes.
 
 ## When a component shows an error
 
@@ -172,6 +176,8 @@ codes you will meet most:
 
 | Code | Meaning | Fix |
 | --- | --- | --- |
+| `prop-unknown` | A prop the component does not accept | Remove it or use a registered prop from the warning or reference |
+| `directive-unclosed` | A block with a body is missing its close | Add `::` at the intended boundary in Markdown source |
 | `query-measure` | The chart has no number per row | Add `group`, `count`, or `sum`, or use `search` |
 | `query-series` | A trend from one value | Use `group`, `daily`, or `search` with `limit` ≥ 2 |
 | `query-escaped-quote` | `\"` inside a query | Use single quotes inside the query |
@@ -180,8 +186,12 @@ codes you will meet most:
 | `chart-body-empty` | No rows in the body | Add `- label: value` rows |
 | `chart-body-number` | A row without a number | Every row needs a numeric value |
 
-An unknown component or attribute is not drawn at all and shows as raw text;
-check names and props against the reference.
+Unknown props preserve the original directive and data through nearby rich
+edits. Closed malformed components can use a reviewed agent replacement and
+undo; missing-close repairs require source editing. Canonical validation and
+strict export reject malformed source until repaired. Never author internal
+recovery nodes such as `bm-problem`. Check component names and props against the
+reference.
 
 ## Checklist
 

skills/memory-comark/references/components.md

@@ -61,7 +61,7 @@ Of these, thirty-one form the deterministic Markdown Graphs vocabulary that stri
 
 ## Use the directive form
 
-Every component is a block directive and must close:
+Author components as closed block directives:
 
 ```markdown
 ::bm-meter{title="Migration" value="0.67" ticks="14" caption="Users table" tone="positive"}
@@ -70,6 +70,35 @@ Every component is a block directive and must close:
 
 Do not put the directive inside a code fence when it should render. Do not treat a code fence as a component when parsing or exporting.
 
+### Authoring errors and repairs
+
+Unknown props produce `prop-unknown`, with the component name, source line and
+registered props. For example, `colour="red"` on `bm-bars` is rejected; it is
+never silently discarded. The reader and rich editor show the affected block in
+its own warning frame with the original directive and data. The rest of the note
+continues rendering, and editing nearby prose preserves the malformed source.
+Remove the unknown prop or replace it with a registered one in Markdown source.
+A closed malformed component also supports a reviewed component replacement and
+undo through the agent tools.
+
+A block with a body but no closing `::` produces `directive-unclosed` near its
+opener. Its warning preserves the opener and any leading YAML properties while
+following headings, lists and prose stay visible outside the frame. Repair the
+source by adding `::` at the intended boundary; the editor never guesses where
+the block ends. Agent component replacements cannot safely claim the rest of an
+unclosed block, so use source editing for this repair.
+
+Existing standalone leaf directives with no body remain valid, though new
+components should use the closed block form above. Nested blocks each need their
+own close. Directive lookalikes inside code fences and escaped literals remain
+literal Markdown.
+
+These diagnostics use the same shared parser in browser rendering, WebMCP and
+the Cloud Comark analyzer. Canonical validation and strict Wiki export reject
+malformed source until repaired. Warning frames are recovery behavior, not a
+new authored vocabulary: never write `bm-problem` or other internal transport
+nodes in a note.
+
 ### Two attribute forms
 
 Inline braces are the compact form. A leading YAML property block, fenced by `---` lines, is the equivalent long form and is required for structured array data.

src/basic_memory/man/man7/comark(7).md

@@ -103,6 +103,8 @@ message.
 | --- | --- |
 | `unknown-element` | The name is not a registered component |
 | `invalid-attribute` | An attribute the component does not accept |
+| `prop-unknown` | An unknown prop; the warning preserves source and lists registered props |
+| `directive-unclosed` | A block with a body has no closing `::`; repair its source boundary |
 | `invalid-attribute-value` | A value outside the attribute's closed set or range |
 | `missing-attribute` | A required attribute is absent |
 | `invalid-chart-body` | The body does not fit the chart; see the `chart-body-*` code |
@@ -118,6 +120,15 @@ message.
 Other `chart-body-*` and `query-*` codes follow the same pattern: the suffix
 names the part of the body or pipeline that is wrong.
 
+Unknown props preserve the original directive and data in their warning frame,
+including through nearby rich edits. Missing-close warnings preserve the opener
+and YAML properties while following Markdown stays visible. Add the close at
+the intended boundary in source; the editor never inserts a guessed close.
+Reviewed agent replacements and undo can repair closed malformed components;
+an unclosed block requires source editing. Canonical validation and strict
+export reject malformed source. Internal recovery nodes such as `bm-problem`
+are never authored.
+
 ## CHECKING YOUR WORK
 
 In Basic Memory Cloud:
@@ -146,7 +157,7 @@ The queue rewrite more than doubled steady-state throughput.
 
 ## GOTCHAS
 
-- [gotcha] An unclosed component swallows the rest of the note into its body.
+- [gotcha] An unclosed block with a body shows `directive-unclosed`; following Markdown stays visible. Standalone leaves with no body remain valid, but author new components with explicit closes.
 - [gotcha] A component inside a code fence is literal code and is not drawn.
 - [gotcha] The rich editor normalizes attribute order and formatting; values survive.
 - [gotcha] A query over a field no note has renders an empty view, not an error.