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:

• examples/guide/catalog.json

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

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

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/**/*.slk modules
• 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, or how do i make a http request resolves to curated task guides, while read from stdin resolves 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 --list results
• exact guide ids render the full guide entry and example or reference source
• id-prefix --show output 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:, or Verified: 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
• --json emits 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_build entries are built,
• verified_run entries are run under a bounded verifier timeout,
• every canonical docs/language/*.md and docs/std/*.md page is covered by at least one guide entry,
• every shipped std export declaration and public method (public fn or public async fn) has generated symbol lookup metadata
• high-traffic diagnostics may point directly at guide queries such as:
• silk guide E2030
• silk guide E2034