symtether is a one-page open spec for #sym:, a portable markdown link fragment that points at a named symbol in source code, plus the reference toolkit that enforces it. When you write [fetchData](src/client.ts#sym:ApiClient.fetchData), the CLI verifies that ApiClient.fetchData still exists in src/client.ts, and fails CI when a reference is broken. The spec is open so other tools can implement it independently.

How do I install symtether?

You do not have to install symtether. Run `npx symtether check` in any repo. There is no config file, no repo indexing, no native compile, and exclusions come from your .gitignore.

Which languages does symtether support?

Eighteen languages resolve at the AST tier via tree-sitter: TypeScript, TSX, JavaScript, Python, Go, Rust, Java, Kotlin, Swift, Ruby, PHP, C, C++, C#, Scala, Elixir, Lua, and Bash. Every other text file falls back to lexical (word-boundary) search, and file-only when the fragment cannot be checked. Every reference reports the tier it resolved at.

How does symtether detect stale documentation?

`symtether update` writes a symtether.sum file that stores a normalized, name-independent SHA-256 content hash of every referenced target. Reformatting does not change a hash. Renaming does not either. `symtether check --strict` flags refs whose target hash no longer matches, and lists every doc that references the changed target. The sum file is optional.

How does symtether integrate with CI and coding agents?

`npx symtether init --ci` scaffolds a GitHub Actions workflow that runs `symtether check` on every pull request. `npx symtether init` also adds a short managed block to AGENTS.md that tells coding agents (Claude Code, Zed, Cursor, etc.) to resolve refs by grepping, run check and fix after renaming symbols, and prefer #sym: refs over line numbers.

Does symtether need a database or repo index?

No. symtether is stateless. It reads the markdown file, resolves each ref against the referenced source file on disk, and exits. No database, no daemon, no repo indexing, no per-repo learning. The symtether.sum file, when it exists, only stores derived hashes and is regenerable at any time.

The `#sym:` reference syntax (SPEC v1)

A #sym: reference is a standard relative markdown link whose fragment names a symbol inside the target source file. It renders and clicks like any other link on GitHub, and symtether verifies each reference against the code.

Canonical form

[link text](<relative-path>#sym:<dotpath>)
[link text](<relative-path>#sym:<kind>:<dotpath>)

<relative-path> is a standard markdown relative path to a source file, resolved relative to the markdown file's own directory (identical to GitHub rendering semantics). Paths beginning with / resolve from the repository root. The repo root is the nearest ancestor containing .git, or the working directory when there is none.
<dotpath> is one or more identifiers joined by ., e.g. ApiClient.fetchData. Each segment must match [A-Za-z0-9_$]+ and is compared case-sensitively.
<kind> is an optional disambiguator from a closed set: fn, class, type, const. (region is reserved for future versions.) An unknown kind is a lint error, not ignored.

Examples:

markdown

[fetch pattern](../src/api/client.ts#sym:ApiClient.fetchData)
[config parsing](src/config.ts#sym:fn:parseConfig)
[shared types](/packages/core/src/types.ts#sym:type:AgentSkill)

Matching semantics

The dotpath is a suffix match against the definition's nesting chain, not a language-exact qualified name.

The resolver extracts all named definitions in the target file as (name, kind, nesting-chain, range) tuples.
A ref matches a definition if the dotpath segments equal the trailing segments of that definition's nesting chain. ApiClient.fetchData matches a method fetchData nested in class ApiClient, even if ApiClient is itself inside a namespace.
If <kind> is present, the matched definition's kind must also map to it.
Exactly one match passes. Zero matches is broken. Two or more matches is ambiguous, an error instructing the author to qualify further by adding a parent segment or a kind.

Compatibility (lenient) forms, read-accepted and never written

On links whose target path resolves to a non-markdown source file, these fragments are accepted with identical semantics and reported with a compat note:

#Symbol (bare)
#Type.method (bare dotpath)

symtether fix --canonicalize rewrites them to #sym: form. Fragments on links targeting markdown files are heading anchors and are never treated as symbol refs.

Out of scope

Line numbers or ranges (#L10), query parameters, version/commit pins, multiple symbols per link, wildcards, regex.

Where refs are recognized

Inline links and reference-style links ([text][id] + [id]: path#sym:X) in .md files.
Ignored: links inside fenced code blocks and inline code spans, image links (![]()), autolinks, external URLs (any scheme), mailto:, and pure-fragment links (#heading).
 suppresses checking for refs on the following line.  and  suppress and restore checking for a block.

The #sym: reference syntax (SPEC v1) ​

Canonical form ​

Matching semantics ​

Compatibility (lenient) forms, read-accepted and never written ​

Out of scope ​

Where refs are recognized ​