@lotics/cli 0.315.13 → 0.315.16

package/docs/knowledge_docs.md

@@ -152,8 +152,9 @@ Retrieval addresses **lines**. Every rule below follows from that one fact.
   40 and its exception on line 90 can be retrieved apart. Use `context_lines` when reading, and
   keep related clauses adjacent when writing.
 
-Markdown headings are ordinary text — useful for a human and for orienting a `read_knowledge`,
-but they carry no retrieval weight of their own.
+Markdown headings are ordinary text — useful for a human (a doc's `##` headings outside its
+blocks, two or more, are listed on its page as its sections) and for orienting a
+`read_knowledge`, but they carry no retrieval weight of their own.
 
 **The description is the discovery hint.** It is what the agent sees in the tree before it has
 read a byte of the body, so it is the only clue for *what term to grep for*. Write it to name
@@ -214,6 +215,25 @@ statement about discovery, so it cannot silently break an app that depends on a
 Reach for it instead of `rm` whenever the material still matters: last year's tariff schedule, a
 handbook a newer one replaced, the raw source a curated doc was written from.
 
+## Formatting — what a doc draws
+
+A doc is markdown with GFM tables. Beyond that it draws a few blocks, each in syntax you already write; the platform draws them in its own style, so every doc looks alike.
+
+| Write | Draws |
+|---|---|
+| `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` opening a blockquote | a callout in that tone |
+| `<Note>`, `<Info>`, `<Tip>`, `<Check>`, `<Warning>`, `<Danger>` | the same callouts |
+| a ```mermaid fence | a diagram: flowchart, sequence, timeline, gantt, `pie`, `xychart-beta`, `quadrantChart` (a 2x2; quadrant-1, top right, is drawn as the target), in the platform's theme; a flowchart's or a 2x2's own colour statements are dropped |
+| `<Steps>` holding `<Step title="…">` | a numbered walk |
+| `<Tabs>` holding `<Tab title="…">` | switchable panels |
+| `<Columns cols={2}>` (or `<CardGroup>`) holding `<Card title="…" href="…" icon="…">` | side-by-side cards that stack on a phone; `icon` is a glyph from the model reference (a select option's mark), and a name it lacks is refused with the nearest |
+| a table whose header cells are all empty | a table with no header row (a key/value table) |
+| `<Accordion title="…">`, `<AccordionGroup>`, or `<details>` with a one-line `<summary>…</summary>` | a section that opens on press |
+
+Each tag stands on a line of its own, and a tag line inside a fenced code block is code. Attributes are text in double quotes or a number in braces; nothing in a tag runs. A write that adds a tag that does not close, nests wrongly, carries an attribute the tag does not take, or names a component this list lacks (`<Frame>`, `<CodeGroup>`) is refused with the lines to fix; lowercase HTML (`<br>`) stays text.
+
+A chart's numbers live in its mermaid source, which agents read and grep like any text: write them there once, not again in a table.
+
 ## Reaching the tools
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.315.13",
+  "version": "0.315.16",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {