@entropicwarrior/sdoc 0.2.6 → 0.2.7

package/README.md

@@ -74,7 +74,17 @@ Key resources for agents:
 | [`docs/reference/sdoc-authoring.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc) | Skill document — drop into context to read/write SDOC immediately |
 | [`lexica/specification.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc) | Formal spec with EBNF grammar |
 
-All `.sdoc` files are designed for progressive disclosure — read the `@about` scope first (~50 tokens), then scan headings, then load only the section you need.
+All `.sdoc` files are designed for progressive disclosure. The JavaScript API provides three functions that let agents navigate without loading entire files:
+
+```javascript
+const { extractAbout, listSections, extractSection } = require("@entropicwarrior/sdoc");
+
+extractAbout(text);              // ~50 tokens — what is this file about?
+listSections(text);              // ~50-100 tokens — what sections does it have?
+extractSection(text, "error-handling"); // ~200-1000 tokens — give me just this section
+```
+
+Total cost for a precise answer: ~750 tokens. The same lookup in Markdown requires loading the full file (5,000-50,000 tokens).
 
 ## Format at a Glance
 
@@ -159,7 +169,7 @@ Markdown-style images with optional width and alignment:
 
 ### Tables
 
-Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely.
+Pipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely. Cells starting with `=` are evaluated as formulas (`=SUM`, `=AVG`, `=COUNT`, arithmetic with A1 cell references).
 
 ### Lists
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -2781,8 +2781,31 @@ function firstParagraphPreview(nodes, maxLen) {
   return "";
 }
 
+/**
+ * Recursively collect all tagged (has @id) scope nodes from the content tree.
+ * Skips @meta and @about. Used for deep section discovery — lets MCP clients
+ * find sections nested inside top-level scopes (e.g. @pass-terminology inside
+ * @pedantic-review inside @writing).
+ */
+function getAllTaggedScopes(nodes) {
+  const result = [];
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "scope") {
+        if (node.id && node.id.toLowerCase() !== "meta" && node.id.toLowerCase() !== "about") {
+          result.push(node);
+        }
+        if (node.children) walk(node.children);
+      }
+    }
+  }
+  const doc = getDocumentScope(nodes);
+  walk(doc ? doc.children : nodes);
+  return result;
+}
+
 function listSections(nodes) {
-  return getContentScopes(nodes).map((node) => ({
+  return getAllTaggedScopes(nodes).map((node) => ({
     id: node.id || null,
     derivedId: slugify(node.title),
     title: node.title,
@@ -2802,7 +2825,7 @@ function collectDataBlocks(children) {
 }
 
 function extractSection(nodes, sectionId) {
-  const scopes = getContentScopes(nodes);
+  const scopes = getAllTaggedScopes(nodes);
 
   function buildResult(node) {
     const data = collectDataBlocks(node.children || []);