smithy-docs-navigator

# Smithy docs navigator ## Overview Smithy's documentation at `https://smithy.io/2.0/` is rendered from reStructuredText and MyST Markdown sources. Reaching a page through a summarizing web-fetch is lossy: it returns a paraphrase that silently drops the exact grammar, trait properties, and normative rules. This skill sends you to the source file and has you read it with a non-summarizing tool, so every answer is grounded in source text rather than memory or a summary. ## Usage Use this skill whenever a request touches Smithy - it is the default way to get an authoritative answer. Concretely: - Authoring or editing a model: shape, resource, operation, or service syntax; the IDL grammar; mixins; shape-ID resolution. - A trait's exact rules and properties (e.g. `@length`, `@http`, `@paginated`, etc.). - Selectors: writing or verifying a selector expression. - HTTP bindings, protocol behavior, or authentication. - Backward compatibility: whether a change breaks customers (the **Evolving Models** guide and the `breakingChanges` rules). - Which code generator to use for a target language, or where to find examples. - Any time a web-fetch of a `smithy.io` page came back summarized or truncated and you are missing the precise constraint, ABNF, or example. Do not use this for non-public, organization-internal conventions - only the published Smithy specification and ecosystem are covered here. ## Core Concepts - **The source file is authoritative. A summary is not.** The rendered HTML, when passed through a summarizing fetch, drops the exact rules you need. Read the source. - **`llms.txt` is the one index.** Published at `https://smithy.io/2.0/llms.txt`, its generated documentation links point at each page's canonical `.rst` or `.md` source (or a `.rst.template`/`.md.template` partial that a page includes), including resolved symlink targets. It also lists curated **Key references** (including backward compatibility), **Examples**, **Code generators by language** (with each generator's language and status where documented), and **Tooling**. There is no separate map to install. - **Read with a non-summarizing tool.** Routing source text back through a summarizing web-fetch loses fidelity just as the HTML did. Use a raw fetch. ## Procedure 1. **Find the page.** Read `https://smithy.io/2.0/llms.txt` (once per session) and pick the entry whose title matches your topic. For cross-cutting questions use its curated sections: backward compatibility -> **Key references**, language codegen -> **Code generators by language**, getting started -> **Examples**. 2. **Use the index for a URL you already have.** The source extension may be `.rst` or `.md` (or a `.rst.template`/`.md.template` partial), and some published pages are symlinks whose canonical source path differs from their rendered URL. The index gives the source URL to read. For a normal reStructuredText page not present in the index, you can rewrite: ``` https://smithy.io/2.0/<path>.html -> https://raw.githubusercontent.com/smithy-lang/smithy/main/docs/source-2.0/<path>.rst ``` Example: `https://smithy.io/2.0/spec/selectors.html` -> `https://raw.githubusercontent.com/smithy-lang/smithy/main/docs/source-2.0/spec/selectors.rst` 3. **Look up a specific trait through the trait index** instead of reading a whole spec page. The trait index at `https://smithy.io/2.0/trait-index.html` lists every trait and links each one to its defining page and section anchor, for example `spec/constraint-traits.html#smithy-api-length-trait`. To answer a trait-specific question: 1. Read the trait index and find the trait's link. The anchor (the part after `#`) is derived from the trait's shape ID, so `#smithy-api-length-trait` is the `smithy.api#length` trait. 2. Read the linked source page through the `llms.txt` index. For this reStructuredText page, `spec/constraint-traits.html` maps to `.../docs/source-2.0/spec/constraint-traits.rst`. 3. Read that `.rst` source and search for the trait's directive line, which names the shape ID directly: `.. smithy-trait:: smithy.api#length`. Read from there down to the next `.. smithy-trait::` directive - that span (its heading, summary, selector, and members) is the authoritative definition of just that one trait, without loading every trait. The trait index's own `.rst` source (`trait-index.rst`) is only the `.. smithy-trait-index::` build directive, so read the rendered `.html` for the index itself, then follow the per-trait links to their `.rst` sources. 4. **Read the full source with a non-summarizing tool** - a shell `curl`, a raw file/URL reader - not a summarizing web-fetch. Both `.rst` and `.md` are plain text: reStructuredText headings are underlined and code sits in `.. code-block:: smithy` blocks; Markdown headings begin with `#`. Their cross-reference roles and links name other pages you can resolve through the same index. 5. **Ground the answer in what you read.** Quote or cite the specific section. If a page cross-references another, resolve that one through the index too rather than relying on memory. ## Notes - The rewrite rule and index target the `2.0` docs on `main`. For another version, adjust the `2.0` segment and the branch/tag in the raw URL. - If a source link 404s, the page may have moved between versions. Re-check the index, then fall back to the rendered `.html` page and read it with a non-summarizing tool.