simdref 0.0.10__tar.gz → 0.0.12__tar.gz

simdref-0.0.12/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: simdref
+Version: 0.0.12
+Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP.
+Author: Marco
+License: GPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.5
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: msgpack<2,>=1.2.1
+Requires-Dist: pdfplumber<1,>=0.11.10
+Requires-Dist: PyMuPDF<2,>=1.28
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: rapidfuzz<4,>=3.14
+Requires-Dist: rich<16,>=15
+Requires-Dist: textual<9,>=8.2
+Requires-Dist: typer<1,>=0.27
+Dynamic: license-file
+
+# simdref
+
+[![CI](https://github.com/simd-labs/simdref/actions/workflows/ci.yml/badge.svg)](https://github.com/simd-labs/simdref/actions/workflows/ci.yml)
+[![TestPyPI](https://img.shields.io/pypi/v/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=TestPyPI)](https://test.pypi.org/project/simdref/)
+[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://pypi.org/project/simdref/)
+
+simdref is a SIMD intrinsic and instruction reference for x86 (Intel +
+uops.info), Arm (ACLE, AARCHMRS), and RISC-V (RVV + unified-db). It runs as
+a CLI, a TUI, an LSP server, and an on-demand manpage renderer.
+
+[Web app](https://simdref.diamondinoia.com/) ·
+[TestPyPI](https://test.pypi.org/project/simdref/) ·
+[GitHub](https://github.com/simd-labs/simdref) ·
+[Contributing](CONTRIBUTING.md)
+
+<p align="center">
+  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/refs/assets/docs/img/tui.svg" width="720">
+</p>
+
+## Install the Claude Code and Codex skill
+
+The `asm-analysis` skill lives in
+[simd-labs/simdref-skill](https://github.com/simd-labs/simdref-skill). Follow
+the install steps in that repo.
+
+## Install
+
+```bash
+pip install simdref
+isa update     # download the pre-built catalog
+isa doctor     # check the install
+isa            # open the TUI
+```
+
+The package installs two equivalent executables, `isa` and `simdref`. The
+catalog download does not need `llvm-mca`. Only `isa build` needs
+`llvm-mca` 18+ on `PATH`.
+
+Pre-release builds live on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ simdref
+```
+
+## Quickstart
+
+```bash
+isa _mm_add_ps       # exact intrinsic  -> detailed view
+isa VPADDD           # exact instruction -> detailed view
+isa _mm_add          # fuzzy -> ranked search results
+isa mm add           # tokenized query -> intrinsic-biased search
+isa ADD              # mnemonic-like -> instruction-biased search
+isa VADDPS 2         # pick variant #2 from the last result list
+isa                  # open the TUI
+```
+
+## Interfaces
+
+The web app at [simdref.diamondinoia.com](https://simdref.diamondinoia.com/)
+reads the JSON site data this repo exports:
+
+```bash
+isa export --out-dir ./site-data
+```
+
+The LSP server speaks JSON-RPC over stdio:
+
+```bash
+simdref-lsp
+```
+
+Editor clients, one for each editor:
+
+- Zed: [zed-simdref](https://github.com/simd-labs/zed-simdref)
+- VS Code: [vscode-simdref](https://github.com/simd-labs/vscode-simdref)
+- JetBrains: [jetbrains-simdref](https://github.com/simd-labs/jetbrains-simdref)
+- Neovim: [nvim-simdref](https://github.com/simd-labs/nvim-simdref)
+
+Each client shows a one-line brief at the end of each instruction line and
+the full manpage on hover, from the local catalog.
+
+The LLM interface emits JSON and NDJSON with exit codes 0 (match), 1 (bad
+flag), 2 (no match), 3 (ambiguous):
+
+```bash
+isa llm query _mm_add_ps --source-kind measured
+echo -e "_mm_add_ps\nVPADDD" | isa llm batch
+isa llm list --pattern "*gather*" --isa Intel
+```
+
+See [docs/LLM.md](docs/LLM.md) for the payload shape.
+
+The annotator turns compiler `.s` output into an annotated `.sa` file.
+
+```bash
+isa annotate hello_simd.s                       # writes hello_simd.sa
+isa annotate hello_simd.s --arch skylake-x -o - # stdout, skylake-x only
+```
+
+The annotator adds a trailing comment with the summary, latency, and CPI to
+each instruction line. The output stays valid assembly.
+
+## Commands
+
+`isa --help` groups commands into Commands and Dev commands.
+
+Commands
+
+| Command                 | Description                                                               |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `isa`                   | Open the TUI                                                              |
+| `isa <query>`           | Open the TUI with the query in a TTY, else print ranked results to stdout |
+| `isa doctor`            | Check the install, non-zero exit on failure                               |
+| `isa update`            | Download the pre-built catalog, `--from-release` for the GitHub Release   |
+| `isa annotate <file.s>` | Annotate a `.s` file with summaries and latency/CPI, writes `<file>.sa`   |
+| `isa man <name>`        | Show a manpage, rendered on demand                                        |
+| `isa install-manpages`  | Pre-generate man7 pages so plain `man vpaddd` works                       |
+| `isa llm query <q>`     | Strict lookup to JSON, NDJSON, or Markdown                                |
+| `isa llm batch`         | Resolve many queries from stdin in one invocation                         |
+| `isa llm list`          | Emit the FilterSpec or stream matching catalog entries                    |
+| `isa llm schema`        | Print the JSON schema for `llm` payloads                                  |
+
+Dev commands
+
+| Command                          | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `isa build`                      | Rebuild the catalog from upstream, needs `llvm-mca` 18+ |
+| `isa export`                     | Export the site-data JSON for the `simdref-web` repo    |
+| `isa completion install [SHELL]` | Install shell completion into the user profile          |
+| `isa completion show [SHELL]`    | Print the completion script                             |
+
+## Data sources
+
+| Source                  | What                                                    | Entries¹           |
+| ----------------------- | ------------------------------------------------------- | ------------------ |
+| Intel Intrinsics Guide  | Signatures, descriptions, ISA, categories               | 7,381 intrinsics   |
+| uops.info               | Instructions, operands, latency, throughput, ports      | 2,558 instructions |
+| Arm ACLE (NEON, SVE)    | Intrinsic signatures and descriptions                   | 10,791 intrinsics  |
+| Arm AARCHMRS (A64)      | Base instruction forms and operand tables               | live-only²         |
+| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs      | 74,289 intrinsics  |
+| RISC-V unified-db       | RVV instruction forms, ISA tags, description, operation | 672 instructions   |
+
+¹ Counts from the vendored snapshot. See
+[`docs/coverage/summary.json`](docs/coverage/summary.json) for parity
+against upstream and [`docs/SOURCES.md`](docs/SOURCES.md) for licenses.
+
+² The full AARCHMRS A64 spec needs a live fetch or a tarball under
+`vendor/arm/`.
+
+Each perf row carries a `(measured, <core>)` or `(modeled, <core>)` tag.
+
+### Scope
+
+- Performance data is x86-only.
+- RISC-V coverage is RVV only, not scalar or privileged ISA.
+
+## Development
+
+```bash
+git clone https://github.com/simd-labs/simdref.git
+cd simdref
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/isa build          # needs llvm-mca 18+
+.venv/bin/python -m pytest tests/ -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+## License
+
+[GNU General Public License v3.0](LICENSE).

simdref-0.0.12/README.md

@@ -0,0 +1,174 @@
+# simdref
+
+[![CI](https://github.com/simd-labs/simdref/actions/workflows/ci.yml/badge.svg)](https://github.com/simd-labs/simdref/actions/workflows/ci.yml)
+[![TestPyPI](https://img.shields.io/pypi/v/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=TestPyPI)](https://test.pypi.org/project/simdref/)
+[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://pypi.org/project/simdref/)
+
+simdref is a SIMD intrinsic and instruction reference for x86 (Intel +
+uops.info), Arm (ACLE, AARCHMRS), and RISC-V (RVV + unified-db). It runs as
+a CLI, a TUI, an LSP server, and an on-demand manpage renderer.
+
+[Web app](https://simdref.diamondinoia.com/) ·
+[TestPyPI](https://test.pypi.org/project/simdref/) ·
+[GitHub](https://github.com/simd-labs/simdref) ·
+[Contributing](CONTRIBUTING.md)
+
+<p align="center">
+  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/refs/assets/docs/img/tui.svg" width="720">
+</p>
+
+## Install the Claude Code and Codex skill
+
+The `asm-analysis` skill lives in
+[simd-labs/simdref-skill](https://github.com/simd-labs/simdref-skill). Follow
+the install steps in that repo.
+
+## Install
+
+```bash
+pip install simdref
+isa update     # download the pre-built catalog
+isa doctor     # check the install
+isa            # open the TUI
+```
+
+The package installs two equivalent executables, `isa` and `simdref`. The
+catalog download does not need `llvm-mca`. Only `isa build` needs
+`llvm-mca` 18+ on `PATH`.
+
+Pre-release builds live on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ simdref
+```
+
+## Quickstart
+
+```bash
+isa _mm_add_ps       # exact intrinsic  -> detailed view
+isa VPADDD           # exact instruction -> detailed view
+isa _mm_add          # fuzzy -> ranked search results
+isa mm add           # tokenized query -> intrinsic-biased search
+isa ADD              # mnemonic-like -> instruction-biased search
+isa VADDPS 2         # pick variant #2 from the last result list
+isa                  # open the TUI
+```
+
+## Interfaces
+
+The web app at [simdref.diamondinoia.com](https://simdref.diamondinoia.com/)
+reads the JSON site data this repo exports:
+
+```bash
+isa export --out-dir ./site-data
+```
+
+The LSP server speaks JSON-RPC over stdio:
+
+```bash
+simdref-lsp
+```
+
+Editor clients, one for each editor:
+
+- Zed: [zed-simdref](https://github.com/simd-labs/zed-simdref)
+- VS Code: [vscode-simdref](https://github.com/simd-labs/vscode-simdref)
+- JetBrains: [jetbrains-simdref](https://github.com/simd-labs/jetbrains-simdref)
+- Neovim: [nvim-simdref](https://github.com/simd-labs/nvim-simdref)
+
+Each client shows a one-line brief at the end of each instruction line and
+the full manpage on hover, from the local catalog.
+
+The LLM interface emits JSON and NDJSON with exit codes 0 (match), 1 (bad
+flag), 2 (no match), 3 (ambiguous):
+
+```bash
+isa llm query _mm_add_ps --source-kind measured
+echo -e "_mm_add_ps\nVPADDD" | isa llm batch
+isa llm list --pattern "*gather*" --isa Intel
+```
+
+See [docs/LLM.md](docs/LLM.md) for the payload shape.
+
+The annotator turns compiler `.s` output into an annotated `.sa` file.
+
+```bash
+isa annotate hello_simd.s                       # writes hello_simd.sa
+isa annotate hello_simd.s --arch skylake-x -o - # stdout, skylake-x only
+```
+
+The annotator adds a trailing comment with the summary, latency, and CPI to
+each instruction line. The output stays valid assembly.
+
+## Commands
+
+`isa --help` groups commands into Commands and Dev commands.
+
+Commands
+
+| Command                 | Description                                                               |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `isa`                   | Open the TUI                                                              |
+| `isa <query>`           | Open the TUI with the query in a TTY, else print ranked results to stdout |
+| `isa doctor`            | Check the install, non-zero exit on failure                               |
+| `isa update`            | Download the pre-built catalog, `--from-release` for the GitHub Release   |
+| `isa annotate <file.s>` | Annotate a `.s` file with summaries and latency/CPI, writes `<file>.sa`   |
+| `isa man <name>`        | Show a manpage, rendered on demand                                        |
+| `isa install-manpages`  | Pre-generate man7 pages so plain `man vpaddd` works                       |
+| `isa llm query <q>`     | Strict lookup to JSON, NDJSON, or Markdown                                |
+| `isa llm batch`         | Resolve many queries from stdin in one invocation                         |
+| `isa llm list`          | Emit the FilterSpec or stream matching catalog entries                    |
+| `isa llm schema`        | Print the JSON schema for `llm` payloads                                  |
+
+Dev commands
+
+| Command                          | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `isa build`                      | Rebuild the catalog from upstream, needs `llvm-mca` 18+ |
+| `isa export`                     | Export the site-data JSON for the `simdref-web` repo    |
+| `isa completion install [SHELL]` | Install shell completion into the user profile          |
+| `isa completion show [SHELL]`    | Print the completion script                             |
+
+## Data sources
+
+| Source                  | What                                                    | Entries¹           |
+| ----------------------- | ------------------------------------------------------- | ------------------ |
+| Intel Intrinsics Guide  | Signatures, descriptions, ISA, categories               | 7,381 intrinsics   |
+| uops.info               | Instructions, operands, latency, throughput, ports      | 2,558 instructions |
+| Arm ACLE (NEON, SVE)    | Intrinsic signatures and descriptions                   | 10,791 intrinsics  |
+| Arm AARCHMRS (A64)      | Base instruction forms and operand tables               | live-only²         |
+| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs      | 74,289 intrinsics  |
+| RISC-V unified-db       | RVV instruction forms, ISA tags, description, operation | 672 instructions   |
+
+¹ Counts from the vendored snapshot. See
+[`docs/coverage/summary.json`](docs/coverage/summary.json) for parity
+against upstream and [`docs/SOURCES.md`](docs/SOURCES.md) for licenses.
+
+² The full AARCHMRS A64 spec needs a live fetch or a tarball under
+`vendor/arm/`.
+
+Each perf row carries a `(measured, <core>)` or `(modeled, <core>)` tag.
+
+### Scope
+
+- Performance data is x86-only.
+- RISC-V coverage is RVV only, not scalar or privileged ISA.
+
+## Development
+
+```bash
+git clone https://github.com/simd-labs/simdref.git
+cd simdref
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/isa build          # needs llvm-mca 18+
+.venv/bin/python -m pytest tests/ -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+## License
+
+[GNU General Public License v3.0](LICENSE).

{simdref-0.0.10 → simdref-0.0.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simdref"
-version = "0.0.10"
+version = "0.0.12"
 description = "Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP."
 readme = "README.md"
 requires-python = ">=3.10"

{simdref-0.0.10 → simdref-0.0.12}/src/simdref/lsp.py

@@ -83,17 +83,32 @@ def _word_at(text: str, line: int, character: int) -> str | None:
     if line >= len(lines):
         return None
     current = lines[line]
+    character = _code_point_index(current, character)
     for match in WORD_RE.finditer(current):
         if match.start() <= character <= match.end():
             return match.group(0)
     return None
 
 
+def _code_point_index(line: str, character: int) -> int:
+    # LSP columns count UTF-16 code units; Python indexes code points.
+    units, index = 0, 0
+    while index < len(line) and units < character:
+        units += 2 if ord(line[index]) > 0xFFFF else 1
+        index += 1
+    return index
+
+
+def _utf16_column(line: str, index: int) -> int:
+    # The reverse of _code_point_index: a code-point index to a UTF-16 column.
+    return sum(2 if ord(c) > 0xFFFF else 1 for c in line[:index])
+
+
 def _line_prefix(text: str, line: int, character: int) -> str:
     lines = text.splitlines()
     if line >= len(lines):
         return ""
-    current = lines[line][:character]
+    current = lines[line][: _code_point_index(lines[line], character)]
     match = re.search(WORD_RE.pattern + r"$", current)
     return match.group(0) if match else ""
 
@@ -267,7 +282,9 @@ def _asm_literals(text: str) -> list[tuple[int, str]]:
 
 
 def _in_asm_string(text: str, line: int, character: int) -> bool:
-    offset = sum(len(item) + 1 for item in text.split("\n")[:line]) + character
+    offset = sum(len(item) + 1 for item in text.split("\n")[:line]) + _code_point_index(
+        text.split("\n")[line], character
+    )
     return any(start <= offset <= start + len(body) for start, body in _asm_literals(text))
 
 
@@ -362,7 +379,7 @@ def _inlay_hints(conn, text: str, language_id: str, uri: str, start: int, end: i
             # LSP columns count UTF-16 code units.
             "position": {
                 "line": line,
-                "character": len(source_lines[line].encode("utf-16-le")) // 2,
+                "character": _utf16_column(source_lines[line], len(source_lines[line])),
             },
             "label": _cut_label("; ".join(hints[line])),
             "paddingLeft": True,
@@ -442,16 +459,27 @@ def main() -> int:
             operand_count = None
             operand_text = ""
             if word and allow_instruction:
-                offset = sum(len(item) + 1 for item in text.split("\n")[:line]) + character
+                offset = sum(len(item) + 1 for item in text.split("\n")[:line]) + _code_point_index(
+                    text.split("\n")[line], character
+                )
                 language_id = session.languages.get(uri, "")
                 segment = _asm_line_at(text, language_id, uri, offset)
                 if segment:
                     operand_text = segment
+                    # The C-escape pair "\t" starts a segment in asm("...\n\t...").
+                    # Strip the backslash so the mnemonic survives.
                     parsed = _mnemonic_from_asm_line(
-                        segment, _semicolon_is_comment(language_id, uri)
+                        segment.lstrip("\\"), _semicolon_is_comment(language_id, uri)
                     )
-                    if parsed and parsed[0].casefold() == word.casefold():
-                        operand_count = parsed[1]
+                    if parsed:
+                        if parsed[0].casefold() == word.casefold():
+                            operand_count = parsed[1]
+                        elif word.casefold().endswith(parsed[0].casefold()):
+                            # The raw word can swallow a preceding escape character:
+                            # on "\tvmulps" _word_at reads "tvmulps", but the parsed
+                            # segment names the real mnemonic.
+                            word = parsed[0]
+                            operand_count = parsed[1]
             body = (
                 _hover_markdown(
                     conn,

simdref-0.0.12/src/simdref.egg-info/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: simdref
+Version: 0.0.12
+Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP.
+Author: Marco
+License: GPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.5
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: msgpack<2,>=1.2.1
+Requires-Dist: pdfplumber<1,>=0.11.10
+Requires-Dist: PyMuPDF<2,>=1.28
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: rapidfuzz<4,>=3.14
+Requires-Dist: rich<16,>=15
+Requires-Dist: textual<9,>=8.2
+Requires-Dist: typer<1,>=0.27
+Dynamic: license-file
+
+# simdref
+
+[![CI](https://github.com/simd-labs/simdref/actions/workflows/ci.yml/badge.svg)](https://github.com/simd-labs/simdref/actions/workflows/ci.yml)
+[![TestPyPI](https://img.shields.io/pypi/v/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=TestPyPI)](https://test.pypi.org/project/simdref/)
+[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://pypi.org/project/simdref/)
+
+simdref is a SIMD intrinsic and instruction reference for x86 (Intel +
+uops.info), Arm (ACLE, AARCHMRS), and RISC-V (RVV + unified-db). It runs as
+a CLI, a TUI, an LSP server, and an on-demand manpage renderer.
+
+[Web app](https://simdref.diamondinoia.com/) ·
+[TestPyPI](https://test.pypi.org/project/simdref/) ·
+[GitHub](https://github.com/simd-labs/simdref) ·
+[Contributing](CONTRIBUTING.md)
+
+<p align="center">
+  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/refs/assets/docs/img/tui.svg" width="720">
+</p>
+
+## Install the Claude Code and Codex skill
+
+The `asm-analysis` skill lives in
+[simd-labs/simdref-skill](https://github.com/simd-labs/simdref-skill). Follow
+the install steps in that repo.
+
+## Install
+
+```bash
+pip install simdref
+isa update     # download the pre-built catalog
+isa doctor     # check the install
+isa            # open the TUI
+```
+
+The package installs two equivalent executables, `isa` and `simdref`. The
+catalog download does not need `llvm-mca`. Only `isa build` needs
+`llvm-mca` 18+ on `PATH`.
+
+Pre-release builds live on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ simdref
+```
+
+## Quickstart
+
+```bash
+isa _mm_add_ps       # exact intrinsic  -> detailed view
+isa VPADDD           # exact instruction -> detailed view
+isa _mm_add          # fuzzy -> ranked search results
+isa mm add           # tokenized query -> intrinsic-biased search
+isa ADD              # mnemonic-like -> instruction-biased search
+isa VADDPS 2         # pick variant #2 from the last result list
+isa                  # open the TUI
+```
+
+## Interfaces
+
+The web app at [simdref.diamondinoia.com](https://simdref.diamondinoia.com/)
+reads the JSON site data this repo exports:
+
+```bash
+isa export --out-dir ./site-data
+```
+
+The LSP server speaks JSON-RPC over stdio:
+
+```bash
+simdref-lsp
+```
+
+Editor clients, one for each editor:
+
+- Zed: [zed-simdref](https://github.com/simd-labs/zed-simdref)
+- VS Code: [vscode-simdref](https://github.com/simd-labs/vscode-simdref)
+- JetBrains: [jetbrains-simdref](https://github.com/simd-labs/jetbrains-simdref)
+- Neovim: [nvim-simdref](https://github.com/simd-labs/nvim-simdref)
+
+Each client shows a one-line brief at the end of each instruction line and
+the full manpage on hover, from the local catalog.
+
+The LLM interface emits JSON and NDJSON with exit codes 0 (match), 1 (bad
+flag), 2 (no match), 3 (ambiguous):
+
+```bash
+isa llm query _mm_add_ps --source-kind measured
+echo -e "_mm_add_ps\nVPADDD" | isa llm batch
+isa llm list --pattern "*gather*" --isa Intel
+```
+
+See [docs/LLM.md](docs/LLM.md) for the payload shape.
+
+The annotator turns compiler `.s` output into an annotated `.sa` file.
+
+```bash
+isa annotate hello_simd.s                       # writes hello_simd.sa
+isa annotate hello_simd.s --arch skylake-x -o - # stdout, skylake-x only
+```
+
+The annotator adds a trailing comment with the summary, latency, and CPI to
+each instruction line. The output stays valid assembly.
+
+## Commands
+
+`isa --help` groups commands into Commands and Dev commands.
+
+Commands
+
+| Command                 | Description                                                               |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `isa`                   | Open the TUI                                                              |
+| `isa <query>`           | Open the TUI with the query in a TTY, else print ranked results to stdout |
+| `isa doctor`            | Check the install, non-zero exit on failure                               |
+| `isa update`            | Download the pre-built catalog, `--from-release` for the GitHub Release   |
+| `isa annotate <file.s>` | Annotate a `.s` file with summaries and latency/CPI, writes `<file>.sa`   |
+| `isa man <name>`        | Show a manpage, rendered on demand                                        |
+| `isa install-manpages`  | Pre-generate man7 pages so plain `man vpaddd` works                       |
+| `isa llm query <q>`     | Strict lookup to JSON, NDJSON, or Markdown                                |
+| `isa llm batch`         | Resolve many queries from stdin in one invocation                         |
+| `isa llm list`          | Emit the FilterSpec or stream matching catalog entries                    |
+| `isa llm schema`        | Print the JSON schema for `llm` payloads                                  |
+
+Dev commands
+
+| Command                          | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `isa build`                      | Rebuild the catalog from upstream, needs `llvm-mca` 18+ |
+| `isa export`                     | Export the site-data JSON for the `simdref-web` repo    |
+| `isa completion install [SHELL]` | Install shell completion into the user profile          |
+| `isa completion show [SHELL]`    | Print the completion script                             |
+
+## Data sources
+
+| Source                  | What                                                    | Entries¹           |
+| ----------------------- | ------------------------------------------------------- | ------------------ |
+| Intel Intrinsics Guide  | Signatures, descriptions, ISA, categories               | 7,381 intrinsics   |
+| uops.info               | Instructions, operands, latency, throughput, ports      | 2,558 instructions |
+| Arm ACLE (NEON, SVE)    | Intrinsic signatures and descriptions                   | 10,791 intrinsics  |
+| Arm AARCHMRS (A64)      | Base instruction forms and operand tables               | live-only²         |
+| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs      | 74,289 intrinsics  |
+| RISC-V unified-db       | RVV instruction forms, ISA tags, description, operation | 672 instructions   |
+
+¹ Counts from the vendored snapshot. See
+[`docs/coverage/summary.json`](docs/coverage/summary.json) for parity
+against upstream and [`docs/SOURCES.md`](docs/SOURCES.md) for licenses.
+
+² The full AARCHMRS A64 spec needs a live fetch or a tarball under
+`vendor/arm/`.
+
+Each perf row carries a `(measured, <core>)` or `(modeled, <core>)` tag.
+
+### Scope
+
+- Performance data is x86-only.
+- RISC-V coverage is RVV only, not scalar or privileged ISA.
+
+## Development
+
+```bash
+git clone https://github.com/simd-labs/simdref.git
+cd simdref
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/isa build          # needs llvm-mca 18+
+.venv/bin/python -m pytest tests/ -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+## License
+
+[GNU General Public License v3.0](LICENSE).