feat: Final docs

AGENTS.md

@@ -14,16 +14,7 @@
 - **Location**: `docs/adr/`
 - **Naming**: `ADR-XXXX-short-title-in-kebab-case.md` (`XXXX` is a sequential number).
 - **Index**:
-  - [ADR-0001: Query Parser](docs/adr/ADR-0001-query-parser.md)
-  - [ADR-0002: Diagnostics System](docs/adr/ADR-0002-diagnostics-system.md)
-  - ADR-0003: Query Intermediate Representation (superseded by ADR-0004, ADR-0005, ADR-0006, available via git history)
-  - [ADR-0004: Query IR Binary Format](docs/adr/ADR-0004-query-ir-binary-format.md)
-  - [ADR-0005: Transition Graph Format](docs/adr/ADR-0005-transition-graph-format.md)
-  - [ADR-0006: Dynamic Query Execution](docs/adr/ADR-0006-dynamic-query-execution.md)
-  - [ADR-0007: Type Metadata Format](docs/adr/ADR-0007-type-metadata-format.md)
-  - [ADR-0008: Tree Navigation](docs/adr/ADR-0008-tree-navigation.md)
-  - [ADR-0009: Type System](docs/adr/ADR-0009-type-system.md)
-  - [ADR-0010: Type System v2](docs/adr/ADR-0010-type-system-v2.md)
+  - _(no ADRs yet)_
 - **Template**:
 
   ```markdown
@@ -169,7 +160,7 @@ crates/
   plotnik-macros/      # Proc macros of the project
 docs/
   adr/                 # Architecture Decision Records (ADRs)
-  REFERENCE.md         # Language specification
+  lang-reference.md    # Language specification
 ```
 
 # CLI

README.md

@@ -190,7 +190,7 @@ for (const stmt of result.statements) {
 }
 ```
 
-For the detailed specification, see the [Language Reference](docs/REFERENCE.md).
+For the detailed specification, see the [Language Reference](docs/lang-reference.md).
 
 ## Supported Languages
 

crates/plotnik-cli/Cargo.toml

@@ -9,7 +9,7 @@ documentation = "https://docs.rs/plotnik-cli"
 keywords = ["tree-sitter", "query", "ast", "parser", "cli"]
 categories = ["command-line-utilities", "development-tools"]
 readme = "../../README.md"
-include = ["src/**/*", "Cargo.toml", "docs/REFERENCE.md"]
+include = ["src/**/*", "Cargo.toml"]
 
 [[bin]]
 name = "plotnik"

crates/plotnik-cli/docs/lang-reference.md

@@ -0,0 +1 @@
+../../../docs/lang-reference.md

crates/plotnik-cli/src/cli.rs

@@ -52,12 +52,6 @@ pub enum Command {
         output: OutputArgs,
     },
 
-    /// Print documentation
-    Docs {
-        /// Topic to display (e.g., "reference", "examples")
-        topic: Option<String>,
-    },
-
     /// List supported languages
     Langs,
 

crates/plotnik-cli/src/commands/mod.rs

@@ -1,5 +1,4 @@
 pub mod debug;
-pub mod docs;
 pub mod exec;
 pub mod langs;
 pub mod types;

crates/plotnik-cli/src/main.rs

@@ -33,9 +33,6 @@ fn main() {
                 color: output.color.should_colorize(),
             });
         }
-        Command::Docs { topic } => {
-            commands::docs::run(topic.as_deref());
-        }
         Command::Langs => {
             commands::langs::run();
         }

crates/plotnik-langs/src/lib.rs

@@ -362,4 +362,27 @@ mod tests {
         assert!(lang.resolve_field("name").is_some());
         assert!(lang.resolve_field("fake_field").is_none());
     }
+
+    /// Verifies that languages with "end" keyword assign it a non-zero ID.
+    /// This proves that ID 0 ("end" sentinel) is internal to tree-sitter
+    /// and never exposed via the Cursor API for actual syntax nodes.
+    #[test]
+    #[cfg(all(feature = "ruby", feature = "lua"))]
+    fn end_keyword_has_nonzero_id() {
+        // Ruby has "end" keyword for blocks, methods, classes, etc.
+        let ruby = ruby();
+        let ruby_end = ruby.resolve_anonymous_node("end");
+        assert!(ruby_end.is_some(), "Ruby should have 'end' keyword");
+        assert_ne!(ruby_end, Some(0), "Ruby 'end' keyword must not be ID 0");
+
+        // Lua has "end" keyword for blocks, functions, etc.
+        let lua = lua();
+        let lua_end = lua.resolve_anonymous_node("end");
+        assert!(lua_end.is_some(), "Lua should have 'end' keyword");
+        assert_ne!(lua_end, Some(0), "Lua 'end' keyword must not be ID 0");
+
+        // Both languages still have internal "end" sentinel at ID 0
+        assert_eq!(ruby.node_type_name(0), Some("end"));
+        assert_eq!(lua.node_type_name(0), Some("end"));
+    }
 }

docs/README.md

@@ -0,0 +1,51 @@
+# Plotnik Documentation
+
+Plotnik is a strongly-typed pattern matching language for tree-sitter syntax trees.
+
+## Quick Links by Audience
+
+### Users
+
+- [Language Reference](lang-reference.md) — Complete syntax and semantics
+- [Type System](type-system.md) — How output types are inferred from queries
+
+### Contributors & LLM Agents
+
+- [AGENTS.md](../AGENTS.md) — Project rules, coding standards, testing patterns
+- [Runtime Engine](runtime-engine.md) — VM execution model
+- [Binary Format](binary-format/01-overview.md) — Compiled query format
+
+## Document Map
+
+```
+AGENTS.md              # Project constitution (coding rules, testing, ADRs)
+docs/
+├── README.md          # You are here
+├── lang-reference.md  # Query language syntax and semantics
+├── type-system.md     # Type inference rules and output shapes
+├── runtime-engine.md  # VM state, backtracking, effects
+└── binary-format/     # Compiled bytecode specification
+    ├── 01-overview.md   # Header, sections, alignment
+    ├── 02-strings.md    # String pool and table
+    ├── 03-symbols.md    # Node types, fields, trivia
+    ├── 04-types.md      # Type metadata format
+    ├── 05-entrypoints.md # Public definition table
+    └── 06-transitions.md # VM instructions and data blocks
+```
+
+## Reading Order
+
+New to Plotnik:
+
+1. `lang-reference.md` — Learn the query syntax
+2. `type-system.md` — Understand output shapes
+
+Building tooling:
+
+1. `binary-format/01-overview.md` → through `06-transitions.md`
+2. `runtime-engine.md`
+
+Contributing:
+
+1. `AGENTS.md` — Required reading
+2. ADRs in `docs/adr/` — Architectural context