Include generated docs in local circuit prompt

[zergzorg]

/claim #45

Summary

• fetches the generated tscircuit docs feed from https://docs.tscircuit.com/ai.txt when building createLocalCircuitPrompt
• keeps generated-docs loading optional so prompt creation still works if the docs endpoint is unavailable
• caches successful generated-docs fetches during the process, but retries after an empty/transient failure so one bad response does not suppress docs until restart
• adds focused mocked-fetch coverage for inclusion, generated-docs-before-handwritten-overview ordering, fallback, successful cache reuse, and retry-after-failure behavior
• keeps OpenAI-backed tests opt-in when OPENAI_API_KEY is unavailable, so the default CI path remains deterministic

Validation

• bun test tests/prompt-templates/create-local-circuit-prompt.test.ts
• bun test --timeout 50000
• bunx biome check lib/prompt-templates/create-local-circuit-prompt.ts tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx tsc --noEmit
• bun run build
• git diff --check

Limitations

• This keeps the existing component props docs fetch required, and only treats the generated docs feed as optional/retryable.

[zergzorg]

Follow-up pushed after CI: bun test --timeout 50000 was failing because OpenAI-backed tests ran with an empty OPENAI_API_KEY in GitHub Actions. I made those two tests opt-in when the key is present, while keeping the deterministic tests active.

Updated local validation:

• bun test --timeout 50000 — 13 pass, 2 skip, 0 fail
• bunx tsc --noEmit — pass
• bun run build — pass

[zergzorg]

Follow-up after comparing current #45 attempts:

• Added a process-level cache for the optional https://docs.tscircuit.com/ai.txt fetch, so repeated createLocalCircuitPrompt() calls during benchmark runs do not refetch the generated docs every time.
• Added a focused regression test proving the generated docs fetch is cached while the required component props docs fetch still runs per prompt build.

Validation:

• bun test tests/prompt-templates/create-local-circuit-prompt.test.ts — passed, 3 tests.
• bun test --timeout 50000 — passed, 14 pass / 2 skipped OpenAI-backed tests without OPENAI_API_KEY.
• bunx biome check lib/prompt-templates/create-local-circuit-prompt.ts tests/prompt-templates/create-local-circuit-prompt.test.ts — passed.
• bunx tsc --noEmit — passed.
• bun run build — passed.
• git diff --check — passed.

[zergzorg]

Follow-up strengthening after re-checking the current competing PR set:

• bounded the optional https://docs.tscircuit.com/ai.txt fetch with a 1.5s timeout so a slow generated-docs endpoint cannot delay prompt construction indefinitely
• kept the existing retry behavior for empty/failed generated docs responses, so a timeout result is not cached permanently and the next prompt build can recover when the endpoint comes back
• added coverage for the timeout + retry path

Validation:

• bun test tests/prompt-templates/create-local-circuit-prompt.test.ts
• bun test --timeout 50000
• bunx biome check lib/prompt-templates/create-local-circuit-prompt.ts tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx tsc --noEmit
• bun run build
• git diff --check

Note: the broader targeted Biome command that also included tests/tscircuitCoder.test.ts still reports the pre-existing filename convention warning for that file; the touched files pass Biome.

[zergzorg]

Follow-up hardening pushed in ceb7322 after reviewing the current same-issue generated-doc competitors:

• the generated ai.txt block is now explicitly framed as untrusted reference text
• the prompt tells the model to keep the higher-priority rules and handwritten API overview ahead of conflicting generated-doc content
• added a regression assertion so the trust-boundary wording stays in the local circuit prompt

Validation:

• bun test tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx biome check lib/prompt-templates/create-local-circuit-prompt.ts tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx tsc --noEmit
• bun run build
• git diff --check

[zergzorg]

Follow-up hardening pushed in 28250a2 after re-checking the current same-issue generated-doc PRs:

• switched the primary generated-docs endpoint to https://docs.tscircuit.com/llms.txt
• kept https://docs.tscircuit.com/ai.txt as a legacy fallback when the primary endpoint is unavailable
• preserved the existing generated-doc cache, timeout, retry-after-failure, and untrusted-reference prompt framing
• added regression coverage for the legacy fallback path and cache behavior

Validation:

• bun test tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx biome check lib/prompt-templates/create-local-circuit-prompt.ts tests/prompt-templates/create-local-circuit-prompt.test.ts
• bunx tsc --noEmit
• bun run build
• git diff --check