silk guide
silk guide is the curated example discovery surface for common Silk tasks.
The seeded in-repo corpus is maintained at a floor of 1000 guide entries.
It combines runnable examples with documentation-backed reference guides that
cover every canonical page under docs/language/ and docs/std/.
Fixture-backed guide entries are promoted to build-verified status when they
compile cleanly; any remaining backend-limited exceptions are tracked
explicitly in the catalog and test suite.
It is intended to answer questions such as:
- how do I read a file?
- how do I wait on a task?
- how do I use
std::task? - which example explains a specific diagnostic?
- where is a public std symbol documented?
What It Uses#
The command reads an installed SQLite database at:
<prefix>/share/silk/guide.db
That database is generated from:
Each guide entry carries:
- a stable guide id
- title and summary
- the example or reference source body
- aliases
- tags
- platforms
- std module references
- environment/runtime requirements
- linked documentation references
- related guide ids
- optional diagnostic-code links
- generated public std symbol lookup terms
- verification flags (
verified_build/verified_run)
Query Forms#
Free-text search:
silk guide monotonic sleep
silk guide channel send receive
silk guide http request
silk guide mime content type
silk guide atomic counter
silk guide protobuf schema roundtrip
silk guide unsafe raw memory
Exact metadata filters:
silk guide tags:concurrency
silk guide module:std::task
silk guide tags:reference-guide
silk guide language types
silk guide language atomics
silk guide std io overview
silk guide module:std::mime
silk guide std::http::request
silk guide std::mime::content_type_with
silk guide std::atomic::AtomicU64.fetch_add
silk guide std::dylib::open_self
silk guide ByteSlice.find_bytes
silk guide std::protobuf::Reader.read_key
silk guide GL_TEXTURE_2D
silk guide diag:E2034
silk guide E2034
Exact alias matches are preferred before free-text FTS search:
silk guide read file
silk guide tcp server
Exact guide id:
silk guide fs/file-roundtrip
silk guide --show fs/file-roundtrip
silk guide --show unsafe/raw-memory-checksum
List seeded guides:
silk guide --list
Machine-readable output:
silk guide --json read file
silk guide --json --show fs/file-roundtrip
Overrides#
Use an explicit database path when testing or staging:
silk guide --db /tmp/guide.db read file
Or set:
SILK_GUIDE_DB=/tmp/guide.db
Behavior#
- exact tag/module/diagnostic queries use normalized SQLite metadata tables
- exact public std symbol queries use generated metadata from shipped
std/**/*.slkmodules - exact alias matches are resolved before free-text FTS search
- natural-language guide queries now go through a deterministic intent-routing
pass before FTS search, so task phrasing like
how to read a file,how can i open a file and read it, orhow do i make a http requestresolves to curated task guides, whileread from stdinresolves to the stdin echo guide - free-text search uses a bundled SQLite FTS5 index over guide titles, summaries, source bodies, aliases, keywords, tags, modules, requirements, docs, and linked diagnostics
- text search results print an explicit
matched:reason - non-empty searches that do not match report an error instead of printing the
alphabetical
--listresults - exact guide ids render the full guide entry and example or reference source
- id-prefix
--showoutput may render multiple guides, but generated reference variants that share the same source body are collapsed to one entry, preferring the canonical overview variant - guide text output does not print
Run:,Source:, orVerified:summary fields - guide
Docs:references are rendered as canonical docs URLs such as types - guide source is printed through the configured printer path (or direct source fallback), not wrapped in fenced code blocks
--jsonemits structured search/show payloads for tools and agents:- list-valued metadata is emitted as JSON arrays, not comma-joined strings
- guide catalog verification is test-backed:
- every distinct guide source path is checked,
- fixture-backed seeded entries stay promoted to
verified_build, verified_buildentries are built,verified_runentries are run under a bounded verifier timeout,- every canonical
docs/language/*.mdanddocs/std/*.mdpage is covered by at least one guide entry, - every shipped std
exportdeclaration and public method (public fnorpublic async fn) has generated symbol lookup metadata - high-traffic diagnostics may point directly at guide queries such as:
silk guide E2030silk guide E2034
Source repository · Edit this page · View Markdown