@entropicwarrior/sdoc 0.2.2 → 0.2.3

package/docs/reference/sdoc-authoring.sdoc

@@ -307,7 +307,7 @@ Content of Section B.
 
         # References @references
         {
-            Assign a slug with \`@slug\` on a heading, then reference it anywhere with \`@slug\`:
+            Assign a slug with \`@slug\` on a heading, then reference it elsewhere in the same document with \`@slug\`:
 
             ```
             # Setup @setup {
@@ -318,6 +318,14 @@ Content of Section B.
                 Make sure you complete @setup first.
             }
             ```
+
+            References are **document-local only** — \`@slug\` resolves within the current file. To point a reader to a section in another file, use a link with a fragment:
+
+            ```
+            See [Setup](./other-file.sdoc#setup) for details.
+            ```
+
+            Do not write \`@setup\` when the target scope is in a different file — it will be flagged as a broken reference.
         }
 
         # Code Blocks @code-blocks
@@ -672,6 +680,25 @@ Content of Section B.
             ```
         }
 
+        # Cross-Document @slug References @cross-doc-refs
+        {
+            \`@slug\` references are document-local. Using \`@slug\` to refer to a section in another file produces a broken reference error:
+
+            **Wrong** — \`@setup\` does not exist in this file:
+
+            ```
+            See `getting-started.sdoc` @setup for installation steps.
+            ```
+
+            **Right** — use a link with a fragment:
+
+            ```
+            See [Setup](./getting-started.sdoc#setup) for installation steps.
+            ```
+
+            The fragment (\`#setup\`) matches the target scope's \`@id\`. Use \`\\@\` if you need a literal \`@\` in text without triggering reference resolution.
+        }
+
         # @References Inside Link Labels @refs-in-link-labels
         {
             Inline \`@references\` are parsed everywhere, including inside link labels. If you mention a scope ID in a link label, escape the \`@\` to prevent it being treated as a reference to the current document:

package/lexica/specification.sdoc

@@ -393,6 +393,8 @@ Content of Section B.
         {
             {[.]
                 - A reference is `@id` in text (unescaped)
+                - References are document-local: `@id` resolves to a scope within the same file only. Cross-document reference syntax may be introduced in a future version but is not part of v0.2
+                - To link to a section in another file, use a standard link with a fragment: `[Label](./other-file.sdoc#section-id)`
                 - References link to the scope with that ID
                 - ID uniqueness is strongly recommended; tooling may warn on duplicates
                 - References are parsed inside link labels — use `\@` to include a literal `@` in a link label without triggering a reference

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.2",
+  "version": "0.2.3",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {