@entropicwarrior/sdoc 0.1.14 → 0.1.16

package/README.md

@@ -63,6 +63,20 @@ python3 tools/serve_docs.py docs/
 
 Or use the **SDOC: Browse Documents** command from the VS Code Command Palette.
 
+## For AI Agents
+
+This repo provides an [`llms.txt`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/llms.txt) file at the repo root for AI agent discovery.
+
+Key resources for agents:
+
+| Resource | What it gives you |
+|---|---|
+| [`lexica/sdoc-authoring.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/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 |
+| [`SDOC_GUIDE.md`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/SDOC_GUIDE.md) | Quick reference in Markdown |
+
+All files in `lexica/` are SDOC-format knowledge documents designed for progressive disclosure — read the `@about` scope first (~50 tokens), then scan headings, then load only the section you need.
+
 ## Format at a Glance
 
 ```sdoc

package/llms.txt

@@ -0,0 +1,21 @@
+# SDOC
+
+> A plain-text documentation format with explicit brace scoping. Deterministic parsing, surgical section extraction, and 10-50x token savings compared to Markdown. Zero-dependency JavaScript parser, VS Code extension, slide generation, and PDF export.
+
+SDOC uses `{ }` braces to define document structure explicitly. Two parsers, same input, same tree — always. AI agents can navigate an SDOC knowledge base in ~200 tokens of discovery, then extract exactly the section they need in ~200-1000 tokens, instead of loading entire files at 5,000-50,000 tokens each.
+
+The authoring guide (`sdoc-authoring.sdoc`) is written as an AI agent skill document. Drop it into any agent's context and it can read and write SDOC immediately.
+
+## Docs
+
+- [SDOC Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/sdoc-authoring.sdoc): Skill document — how to write correct SDOC files. Covers document structure, inline formatting, block types (lists, tables, code, blockquotes), mermaid diagrams, and common mistakes. Start here to learn the format.
+- [SDOC Specification](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc): Formal v0.1 specification with EBNF grammar. Defines syntax for scopes, lists, tables, code blocks, inline formatting, references, and the meta scope.
+- [Why SDOC Over Markdown](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/why-sdoc.sdoc): The case for SDOC — structural problems with Markdown, why explicit scoping solves them, parsing safety as a security property, and the adoption path forward.
+- [Quick Reference (Markdown)](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/SDOC_GUIDE.md): Compact reference guide in Markdown format for quick lookup.
+
+## Optional
+
+- [Requirements](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/requirements.sdoc): Why SDOC exists and what it must achieve. Ten abstract requirements (R1-R10) and concrete constraints (C1-C6).
+- [Slide Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/slide-authoring.sdoc): How to create HTML slide decks from SDOC files.
+- [Introduction](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/guide/intro.sdoc): Gentle introduction to the format for newcomers.
+- [Syntax Reference](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/syntax.sdoc): Practical syntax reference with examples.

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