docs: add README; adopt git.sisudoc.org/tools/ namespace

Add a top-level README.md describing what tree-sitter-sisu is, its
audience (editor / IDE tooling maintainers), its relationship to
sisudoc-spine, quickstart instructions for Neovim and Emacs 29+,
and a pointer to the existing sisu-markup_tree-sitter.md for
corpus results and grammar design notes.

Move the canonical repository URL from
https://git.sisudoc.org/software/tree-sitter-sisu to
https://git.sisudoc.org/tools/tree-sitter-sisu in both
package.json and tree-sitter.json. The new tools/ namespace
mirrors the local sisudoc-spine-tools/ directory containing this
and the other spine-companion artefacts (ssp-reader,
doc-abstraction-format), and continues the existing functional
namespace pattern on git.sisudoc.org alongside software/, markup/,
and projects/.

The README's cross-references to ssp-reader and
doc-abstraction-format use the same tools/ namespace.

(assisted by Claude-Code)

3 files changed, 118 insertions, 2 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59d711d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# tree-sitter-sisu
+
+Tree-sitter grammar for **SiSU spine** document markup (`.sst`, `.ssm`,
+`.ssi`).
+
+Provides structural syntax highlighting, folding, and text-object
+queries for any editor that hosts a tree-sitter runtime: Neovim,
+Emacs 29+ (`treesit`), Helix, Zed, and others.
+
+## What this is for
+
+- Editor / IDE syntax highlighting that respects nested inline
+  markup, block bodies, and multi-line footnotes (cases where
+  regex-based highlighters break down).
+- Structural queries: jump heading to heading, fold a block body,
+  select "inside a footnote" or "outside a code block", etc.
+- A second implementation of the SiSU markup parser, useful as a
+  cross-check on the production parser in
+  [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine).
+
+## Audience
+
+Editor tooling maintainers and end users who want SiSU markup
+support inside their editor. Not aimed at end-user document
+authors directly; it is consumed via your editor's tree-sitter
+integration.
+
+## Relationship to spine
+
+This grammar parses the same input syntax as
+[sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine)
+itself. Spine produces the canonical parse used for output
+generation; this grammar provides editor-side parsing for
+highlighting and navigation, and is kept in sync with spine's
+markup rules. See [`sisu-markup_tree-sitter.md`](sisu-markup_tree-sitter.md)
+for the corpus-level test results and known limitations.
+
+## Quickstart
+
+### Neovim (via nvim-treesitter)
+
+The simplest path is to use the Neovim drop-in shipped by spine
+itself:
+
+```sh
+# clone sisudoc-spine
+git clone --depth=1 git://git.sisudoc.org/software/sisudoc-spine
+
+# add to runtime path
+ln -s "$PWD/sisudoc-spine/sundry/editor-syntax-etc/nvim" \
+      "$HOME/.config/nvim/pack/sisu/start/sisu-spine"
+```
+
+then in your `init.lua`:
+
+```lua
+require("sisu-spine").setup()
+require("nvim-treesitter.configs").setup({
+  ensure_installed = { "sisu" },
+  highlight = { enable = true },
+  fold      = { enable = true },
+  indent    = { enable = true },
+})
+```
+
+and `:TSInstall sisu` builds and registers this parser.
+
+### Emacs 29+
+
+```elisp
+(add-to-list 'treesit-language-source-alist
+  '(sisu "https://git.sisudoc.org/tools/tree-sitter-sisu"
+         :source-dir "src"))
+;; M-x treesit-install-language-grammar RET sisu RET
+```
+
+A complete major mode that uses this parser lives in spine's
+`sundry/editor-syntax-etc/emacs/sisu-spine-ts-mode.el`.
+
+### Build locally
+
+```sh
+nix-shell -p tree-sitter nodejs --run "tree-sitter generate"
+nix-shell -p tree-sitter nodejs --run "tree-sitter test"
+nix-shell -p tree-sitter nodejs --run "tree-sitter parse path/to/doc.sst"
+```
+
+## Documentation
+
+- [`sisu-markup_tree-sitter.md`](sisu-markup_tree-sitter.md) -
+  detailed notes on what the grammar parses, corpus test results,
+  known limitations, and the rationale for grammar design choices.
+- [`queries/`](queries/) - tree-sitter queries: `highlights.scm`,
+  `folds.scm`, `textobjects.scm`, `indents.scm`, `injections.scm`.
+- [`test/corpus/`](test/corpus/) - unit-test corpus.
+
+## License
+
+AGPL-3.0-or-later. See [`package.json`](package.json) and the
+parent [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine)
+project for full licence text.
+
+## Repository
+
+- **Canonical URL:** https://git.sisudoc.org/tools/tree-sitter-sisu
+- **Clone:** `git clone --depth=1 git://git.sisudoc.org/tools/tree-sitter-sisu`
+
+## Related projects
+
+- [sisudoc-spine](https://git.sisudoc.org/projects/sisudoc-spine) -
+  the SiSU spine document engine (D) that consumes this markup.
+- [sisudoc-spine-samples](https://git.sisudoc.org/markup/sisudoc-spine-samples) -
+  corpus of real SiSU documents this grammar is tested against.
+- [ssp-reader](https://git.sisudoc.org/tools/ssp-reader) -
+  reader for the `.ssp` document-abstraction text format that
+  spine emits.
diff --git a/package.json b/package.json
index 5d0986d..8fa5908 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://git.sisudoc.org/software/tree-sitter-sisu"
+    "url": "https://git.sisudoc.org/tools/tree-sitter-sisu"
   },
   "main": "bindings/node",
   "types": "bindings/node/index.d.ts",
diff --git a/tree-sitter.json b/tree-sitter.json
index f3ccebb..0d9bc11 100644
--- a/tree-sitter.json
+++ b/tree-sitter.json
@@ -28,7 +28,7 @@
       }
     ],
     "links": {
-      "repository": "https://git.sisudoc.org/software/tree-sitter-sisu"
+      "repository": "https://git.sisudoc.org/tools/tree-sitter-sisu"
     }
   }
 }