[thekevinbot]

Fixes #1264

dirsql context prints a usage guide for agents, matched to the running version. The first line is dirsql <version>, followed by the sections ## Usage, ## Recipes and ## Troubleshooting. It takes no flags and exits 0.

• Where the guide comes from: the body of PR feat: add a /dirsql agent skill for querying a directory #1235's SKILL.md plus its recipes.md and troubleshooting.md, ported to docs/context/*.md (1,363 words) and compiled into the binary with include_str!. The packages/rust/docs symlink means the files ship in the crate.
• Corrections from review:
  • The guide describes only what main does today, and avoids claims that feat(core): path-tables hide dot-named entries unless the path spells them #1252, A trailing slash on a path-table is a star appended #1260 or Brace groups follow bash: no comma or sequence means literal #1263 would make false.
  • node_modules is skipped unless the path names it.
  • .git is entered only when named.
  • The json_each recipe is guarded with json_valid.
  • The glob rules are stated as: * is one level, ** is any depth, a named directory lists one level, .gitignore is respected, and --no-ignore turns that off.
• Launchers: the Python and TS launchers pass context through untouched, as they already do for init. Without that, installed plugins or a config extension would append flags that context rejects.
• Docs site: docs/context/** is excluded from VitePress, and reference/cli.md documents the subcommand.
• Line endings: docs/context/.gitattributes forces LF, so the Windows binary does not embed CRLF.

Tests

• packages/rust/tests/context_integration.rs checks the output contract: exit 0 with empty stderr, the version line, the three sections in order, and that a flag is a usage error (exit 2).
• packages/rust/tests/context_examples_e2e.rs is the drift guard. It runs every fenced uvx dirsql ... example from the printed guide against a fixture that includes an empty metadata.json, and asserts each exits 0 with a JSON array.
  • The plugin example (uvx --with dirsql-plugin-embeddings) is skipped because it downloads a model.
  • Removing the json_valid guard locally made the guard fail with malformed JSON.
• Unit tests cover cli/context.rs, the Command::Context parse and dispatch, and both launchers.
• Red CI run for the test-only commit: https://github.com/thekevinscott/dirsql/actions/runs/37316706463. All four integration tests and the drift guard failed with SQLite error: near "context": syntax error.

Manual run

I built the binary and ran it in an unrelated directory, /tmp/ctx1264-manual:

• dirsql context exited 0. Its first line was dirsql 0.2.7, and the three ## sections appeared in order.
• I ran these printed examples, and each returned the expected JSON:
  • the largest files
  • the json_each tags query over a directory containing an empty metadata.json
  • the frontmatter LIKE query
  • './notes', which listed one level only
• dirsql context --format json exited 2 with unexpected argument '--format'.

E2E Verification

• just e2e-attest-python: 39 passed, 1 xfailed. The receipt is committed.
• just e2e-attest-ts: passed. The receipt is committed.
• cargo test --features cli for the context tests and the drift guard: passed.
• just preflight with the colocated-test, one-function-per-file, unit-lint, integration-lint, unit-coverage, packaging and e2e-verify gates: 0 failing.
• An earlier Python e2e attempt failed one speed-of-light timing test while the host load average was over 70. It passed once the load dropped.

Changelog / Migrations

• packages/rust/changelog.d/2026-10-05-cli-context.md and migrations.d/ twin
• packages/python/changelog.d/2026-10-05-cli-context.md and migrations.d/ twin
• packages/ts/changelog.d/2026-10-05-cli-context.md and migrations.d/ twin

Parity

This is CLI-only. No SDK API changed, so PARITY.md has no drift.

Note: the guide lives under the root docs/context/, outside packages/*. A later edit that touches only the guide will not trigger a release by itself.