[icostan]

Adds StreamData-specific usage rules covering setup, generator composition, shrinking behavior, common
pitfalls, configuration, and property-testing patterns. These rules help AI coding agents use and test
StreamData correctly.

[whatyouhide]

@icostan I’m sorry—I have zero context on this. Help please? 🙃

[icostan]

@whatyouhide This PR adds agent-focused guidance for using StreamData. The usage_rules library discovers these files
in project dependencies and syncs them into AGENTS.md or agent skills, giving AI agents fast, version-
local guidance on the correct APIs, testing patterns, and common mistakes—without making them search
broadly or guess.

[icostan]

Pushed an update (f42d683):

• Packaged: usage-rules.md is now in the Hex package via package[:files]. Before this it wasn't shipped, so usage_rules had nothing to find. I compared mix hex.build --unpack before and after: this file is the only addition.
• Trimmed: the file went from 89 lines to about 40. I removed everything that repeated the README or the moduledocs (setup, config, the list of options for each generator). What's left are the pitfalls agents tend to hit, like losing shrinking via Stream/Enum, filter vs map, and putting simpler choices first in one_of.
• Docs lookup: for everything else, it points agents to mix usage_rules.search_docs "…" -p stream_data. mix usage_rules.docs doesn't work here: StreamData is usually a test-only dependency, so it can't be loaded in the dev env, and MIX_ENV=test doesn't help either. I ran every command in the file before adding it.

[whatyouhide]

Right, but how do agents discover these? Isn't this covered decently by ex_doc generating llms.txt? Aren't today's agents smart enough to look at that first?

[icostan]

A few key differences:

1. Pull: Agents rarely fetch remote docs proactively—they generate from training weights
   unless prompted. Running mix usage_rules.sync in a project pulls usage-rules.md from deps/ directly
   into AGENTS.md or local skills, so the rules are in context upfront.
2. Local & version-locked: llms.txt lives on HexDocs and requires network access. usage-rules.md is
   local and locked to the exact version in mix.lock.
3. Pitfalls vs. full API: llms.txt indexes entire reference docs. usage-rules.md is just ~35 lines
   of StreamData-specific pitfalls models repeatedly hit (losing shrinking via Stream/Enum, narrow
   filters, etc.) that fit permanently in context.

[whatyouhide]

With today's models this feels heavy handed and I don't necessarily want to keep this in sync, so I'll skip this for now. I’m sure the usage_rules package has a way to generate these for deps without having to commit them upstream. Thanks!